prsc

library4.0.0jsnpmunverified

prsc is a compact parser combinators library for both JavaScript and TypeScript, heavily influenced by the Rust parsing library `nom`. It enables developers to construct complex parsers from simpler ones for string inputs, offering primitive parsers like `token` and combinators such as `map`, `filter`, `then`, and `star`. The library ships with ES6 modules (`.mjs`), UMD bundles (`.js`), and comprehensive TypeScript typings, facilitating its use across various environments, including Node.js and browsers. The current stable version is 4.0.0. Releases are somewhat frequent, with minor features and bug fixes rolled out between major versions, indicating active maintenance and continuous improvement in performance and usability for writing fast, reliable parsers.

serialization

npm install prsc

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PRSC

prsc

serializationjavascriptv4.0.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.

Parser

✓ import type { Parser } from 'prsc';

✗ import { Parser } from 'prsc';

Use `import type` when only referencing the type in TypeScript to prevent accidental runtime imports and aid tree-shaking.

ok, error

✓ import { ok, error } from 'prsc';

✗ const { ok, error } = require('prsc');

The library primarily uses ESM imports. While UMD bundles are provided, the `require` syntax is generally discouraged for modern Node.js environments and TypeScript projects, especially since v4.0.0 improved ESM compatibility.

map, then, star, recognize, token, plus, preceded, optional

✓ import { map, then, star, recognize, token, plus, preceded, optional } from 'prsc';

✗ import * as prsc from 'prsc'; prsc.map(...);

These are common named exports representing core combinators. Destructuring them directly is the idiomatic way to use them.

This example demonstrates building a parser for a simple arithmetic language supporting addition and multiplication, showcasing primitive parsers, combinators like `map`, `then`, `star`, and handling recursive grammar rules.

import { ok, error, map, recognize, plus, then, token, star, preceded, optional } from 'prsc'; // Create a primitive parser that accepts a single digit const digit = (input, offset) => { if (/^[0-9]$/.test(input[offset])) { return ok(offset + 1, input[offset]); } return error(offset, ['digit']); }; // Use that to accept a string of one or more digits const digits = plus(digit); // Then use recognize to get the matching string and use map to parse that into a number const number = map(recognize(digits), (str) => parseInt(str, 10)); // Multiplication: term = number * term // Recursive definition requires indirection for `factor` const termIndirect = (input, offset) => term(input, offset); const factor = then( number, optional(preceded(token('*'), termIndirect)), (num, optFactor) => (optFactor ? num * optFactor : num) ); // Addition: expression = factor + expression const expressionIndirect = (input, offset) => expression(input, offset); const expression = then( factor, star(preceded(token('+'), expressionIndirect)), (firstFactor, additionalFactors) => additionalFactors.reduce((sum, f) => sum + f, firstFactor) ); // Parsing some input const result1 = expression('2*3+4*5', 0); console.log(result1); // Expected: { success: true, offset: 7, value: 26 } const result2 = expression('10+20*2', 0); console.log(result2); // Expected: { success: true, offset: 7, value: 50 } (10 + (20 * 2))

Debug

Known issues

breakingVersion 4.0.0 primarily fixes ESM usage in Node.js environments. This is a breaking change because it renames the UMD module file provided for older CJS environments, which might affect direct file path references.

fix

Ensure you are using standard ESM imports (`import ... from 'prsc'`) in Node.js and modern browser environments. If you rely on direct paths to the UMD bundle for CJS, check the new file names in `dist/`.

affects: 4.0.0

breakingIn version 3.0.0, the `range` parser no longer returns a value directly. It now acts purely as a consumption parser.

fix

If you need the matched string value from `range`, combine it with the `recognize` combinator: `map(recognize(range(...)), value => ...)`.

affects: >=3.0.0

gotchaWhen defining recursive parsers (e.g., `expression = term + expression`), it's crucial to use a layer of indirection (e.g., `termIndirect` function) to avoid circular dependencies in JavaScript module loading or infinite recursion at runtime.

fix

Wrap the recursive parser call in a function (e.g., `const parser = (input, offset) => actualParser(input, offset);`) and pass this function for the recursive part.

affects: all

gotchaAn infinite loop can occur if a parser given to `star` (or `plus`) does not consume any input. While fixed for `star` in v2.1.0, this remains a common logical error for custom parsers.

fix

Always ensure that parsers wrapped by `star` or `plus` consume at least one unit of input if they succeed. If a parser fails to consume input, it should return an `error` result.

affects: <2.1.0

Errors

Common errors & fixes

TypeError: Parser is not a constructor

Attempting to import `Parser` as a runtime value rather than a type in TypeScript, or incorrect CommonJS `require` syntax.

fix

For TypeScript, use `import type { Parser } from 'prsc';`. For JavaScript, you likely don't need to import `Parser` itself as it's a type, not a runtime class.

TypeError: Cannot read properties of undefined (reading 'map') or similar 'not a function' errors

Incorrect import of combinators (e.g., `map`, `then`, `star`). This often happens with CommonJS `require` on ESM-only versions or attempting to access named exports via a default import.

fix

Ensure you are using named ESM imports: `import { map, then } from 'prsc';`. Avoid `const prsc = require('prsc'); prsc.map;` for modern versions.

ParserError: Expected range at offset X but got Y (or similar error when using `range`)

Using `range` parser from v3.0.0 onwards and expecting it to return a value, which it no longer does directly.

fix

If you need the value, wrap `range` with `recognize`: `const valueParser = map(recognize(range('a', 'z')), str => str);`.

Upgrade

Version history

4.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

13 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/bwrrp/prsc.js ↗

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

homepagehttps://prsc.js.org ↗