parsimmon

library1.18.1jsnpmunverified

Parsimmon is a compact, monadic LL(infinity) parser combinator library for JavaScript, enabling the construction of complex parsers from smaller, composable units. It is currently at version 1.18.1 and supports both modern Node.js environments and older browser versions (down to IE7). Its release cadence appears to be infrequent, with the last major feature release (1.7.0) being in 2018, though bug fixes and minor updates have occurred more recently. Key differentiators include its inspiration from Haskell's Parsec and Promises/A+ for its API design, its support for binary parsing using Node.js Buffers, and its compatibility with the Fantasy Land specification, implementing several algebraic structures like Semigroup, Apply, Applicative, Functor, Chain, and Monad. It distinguishes itself by offering a functional and declarative approach to parsing, making grammars easy to read and maintain.

serialization

npm install parsimmon

github ↗package ↗

INSTALL

IMPORT

SIG · PARSIMMON

parsimmon

serializationjavascriptv1.18.1

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.

Parsimmon

✓ import Parsimmon from 'parsimmon'

✗ const Parsimmon = require('parsimmon').Parsimmon

Parsimmon exports itself as the default, making named imports unnecessary for the top-level object. For CommonJS, `require('parsimmon')` directly returns the Parsimmon object.

Parsimmon.string

✓ import Parsimmon from 'parsimmon'; const myParser = Parsimmon.string('hello');

✗ import { string } from 'parsimmon';

Most core parser functions are static methods on the `Parsimmon` object, not named exports. Destructuring directly from the package root is incorrect for these.

parser.map

✓ import Parsimmon from 'parsimmon'; const myParser = Parsimmon.string('hello').map(s => s.toUpperCase());

✗ import { map } from 'parsimmon'; map(parser, fn);

Parser combinators like `map` are methods on a `Parsimmon` parser instance, intended for chaining, following a monadic style.

Parsimmon.createLanguage

✓ import Parsimmon from 'parsimmon'; const language = Parsimmon.createLanguage({});

✗ const { createLanguage } = require('parsimmon');

Similar to `Parsimmon.string`, `createLanguage` is a static method of the main `Parsimmon` object, not a direct named export from the module.

Demonstrates defining basic parsers for digits and operators, combining them to parse arithmetic expressions and comma-separated lists, and handling parse results.

import Parsimmon from 'parsimmon'; // Define basic parsers const digit = Parsimmon.regexp(/[0-9]/); const plus = Parsimmon.string('+'); const minus = Parsimmon.string('-'); // Combine parsers to recognize an integer (one or more digits) const integer = digit.atLeast(1).map(digits => parseInt(digits.join(''), 10)); // Combine parsers to recognize an operator const operator = plus.or(minus); // Define a parser for a simple arithmetic expression like '123+45' const expression = Parsimmon.seq(integer, operator, integer).map( ([left, op, right]) => { if (op === '+') return left + right; if (op === '-') return left - right; return NaN; // Should not happen with defined operators } ); // Parse some input strings const result1 = expression.parse('123+45'); const result2 = expression.parse('99-10'); const result3 = expression.parse('5*2'); // Will fail console.log('Result for "123+45":', result1); console.log('Result for "99-10":', result2); console.log('Result for "5*2" (expected failure):', result3); // Example of parsing a more complex structure (e.g., a comma-separated list of numbers) const comma = Parsimmon.string(','); const listOfNumbers = integer.sepBy(comma).map(nums => nums.join(', ')); const listResult = listOfNumbers.parse('1,2,3,4,5'); console.log('List of numbers for "1,2,3,4,5":', listResult);

Debug

Known issues

gotchaParsimmon is primarily a CommonJS module with UMD builds for browsers. While Node.js can import CommonJS modules using `import`, it only supports default imports for the entire module. Directly named imports for static methods (e.g., `import { string } from 'parsimmon'`) will not work as expected in an ESM context.

fix

Always import the main `Parsimmon` object as a default import (e.g., `import Parsimmon from 'parsimmon'`) and access static methods or parser methods via `Parsimmon.<methodName>` or `parserInstance.<methodName>`.

affects: >=1.0.0

breakingIn version 1.0.0, `parser.empty` was changed from a property to a function (`parser.empty()`), and `f.ap(x)` was changed to `x.ap(f)` to align with Fantasy Land specifications. Code using the old syntax for these specific combinators will break.

fix

Update `parser.empty` calls to `parser.empty()` and adjust the order of arguments for `ap` to `x.ap(f)`.

affects: 1.0.0

breakingIn version 0.9.1, `Parsimmon.seqMap` began throwing an error when called with zero arguments or if the final argument was not a function. This enforces correct usage of the combinator.

fix

Ensure `Parsimmon.seqMap` is always called with at least one parser argument and that the last argument is a mapping function.

affects: 0.9.1

breakingIn version 0.9.0, `Parsimmon.regexp` (aliased as `P.regex` previously) was updated to throw an error if the regular expression included flags other than `i` (case-insensitive), `m` (multiline), or `u` (unicode). This might affect parsers relying on unsupported regex flags.

fix

Review `Parsimmon.regexp` usage and ensure only `i`, `m`, or `u` flags are used. Adjust regular expressions or parsing logic if other flags were previously relied upon.

affects: 0.9.0

gotchaThe library's development seems less active recently, with the latest significant feature release (v1.7.0) being in 2018, though maintenance updates exist. While stable and well-tested (100% coverage since 1.6.1), rapid introduction of new features or quick resolution of complex issues might not be expected.

fix

Evaluate active community support and contribution patterns on the GitHub repository for critical, time-sensitive projects. Consider contributing or preparing for self-maintenance if specific niche features or rapid development are required.

affects: >=1.7.0

Errors

Common errors & fixes

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

Attempting to destructure static methods from the `parsimmon` module in an ESM context (e.g., `import { string } from 'parsimmon';`) when the module is a CJS default export.

fix

Import the `Parsimmon` object as a default import and access methods via `Parsimmon.string` (e.g., `import Parsimmon from 'parsimmon'; const myParser = Parsimmon.string('hello');`).

ReferenceError: Parsimmon is not defined

In a browser environment, the `Parsimmon` global is not available because the UMD build was not loaded via a script tag, or in a Node.js environment where `require()` or `import` was not used correctly.

fix

For browsers, ensure a `<script>` tag loading the UMD build (e.g., from unpkg) is present before attempting to use `Parsimmon`. For Node.js, use `const Parsimmon = require('parsimmon');` or `import Parsimmon from 'parsimmon';` to import the library.

Error: Expected a character in the range 'x' to 'y' but got "..."

A parser combinator like `Parsimmon.range(begin, end)` or `Parsimmon.letter` encountered an unexpected character in the input string, indicating a mismatch between the parser's expectation and the actual data.

fix

Inspect the input string for unexpected characters or malformed data. Adjust the parser definition to correctly handle the expected input format, or add `.or()` combinators to handle alternative valid patterns. The error message from `parser.parse(input)` usually provides line and column details.

Upgrade

Version history

1.18.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/jneen/parsimmon ↗

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