parser-ts

library0.7.0jsnpmunverified

`parser-ts` is a library providing string parser combinators for TypeScript, heavily influenced by the `purescript-eulalie` library and built upon the foundational `fp-ts` functional programming toolkit. It enables developers to construct complex parsers by combining simpler parsing functions in a declarative manner, leveraging `fp-ts`'s algebraic data types and functional patterns. The current stable version is 0.7.0, with releases occurring periodically to address bugs, introduce new combinators, and align with `fp-ts` peer dependency updates. Its key differentiators include its strong TypeScript typing, functional purity, and close integration with the `fp-ts` ecosystem, making it suitable for applications requiring robust and composable parsing logic within a functional TypeScript codebase. The library primarily focuses on string parsing and is often used for creating DSLs, configuration file parsers, or simple language frontends.

serialization http-networking

npm install parser-ts

github ↗package ↗

INSTALL

IMPORT

SIG · PARSER-TS

parser-ts

serializationjavascriptv0.7.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.

string

✓ import { string } from 'parser-ts/string'

✗ import { string } from 'parser-ts'

Specific combinators like `string`, `char`, `digit`, etc., are typically imported from their respective sub-modules (e.g., `parser-ts/string`, `parser-ts/char`) for better tree-shaking and module organization.

Parser

✓ import { Parser, run } from 'parser-ts/Parser'

✗ import { Parser } from 'parser-ts'

The core `Parser` type and functions to execute a parser, such as `run` and `runStrict`, are located in the `parser-ts/Parser` module. It's common to import both the type and a runner.

pipe

✓ import { pipe } from 'fp-ts/function'

✗ import { pipe } from 'parser-ts'

`pipe` is a fundamental utility from `fp-ts` used extensively with `parser-ts` for composing functional operations in a readable, left-to-right manner. It is not exported directly by `parser-ts`.

This quickstart demonstrates how to define a parser for a comma-separated list of integers using basic combinators like `char`, `many1`, `recognize`, `map`, and `sepBy`, and then run it against various inputs.

import { pipe } from 'fp-ts/function'; import * as P from 'parser-ts/Parser'; import * as S from 'parser-ts/string'; import * as C from 'parser-ts/char'; import * as E from 'fp-ts/Either'; // Define a parser for one or more digits, then convert to an integer const integerParser = pipe( S.recognize(C.many1(C.digit)), // `recognize` captures the matched string P.map(parseInt) // `map` transforms the parsed string to a number ); // Define a parser for a literal comma character const commaParser = C.char(','); // Define a parser for a list of integers separated by commas // `sepBy` applies `integerParser`, consuming `commaParser` in between const commaSeparatedIntegersParser = pipe( integerParser, P.sepBy(commaParser) ); // Helper function to run the parser and log results const parseNumbers = (input: string) => { console.log(`\nAttempting to parse: "${input}"`); const result = P.run(commaSeparatedIntegersParser, input); E.match( (error) => console.error('Parse Error:', error.message, 'at position', error.offset), ([value, remaining]) => console.log('Parsed Value:', value, '| Remaining Input:', remaining.length === 0 ? 'None' : `"${remaining}"`) )(result); }; // Example Usage parseNumbers('1,2,3,4'); parseNumbers('100'); parseNumbers('1, 2, 3'); // Fails due to unexpected space parseNumbers('abc'); parseNumbers('1,2,abc');

Debug

Known issues

breakingVersion 0.7.0 upgraded the `fp-ts` peer dependency to `^2.14.0`. Projects using an older `fp-ts` version (e.g., `<2.14.0`) will need to upgrade `fp-ts` to a compatible version, or `npm`/`yarn` might report peer dependency conflicts and potentially install an incompatible version, leading to type mismatches or runtime errors.

fix

Upgrade `fp-ts` to a compatible version (`^2.14.0` or later) in your project: `npm install fp-ts@^2.14.0` or `yarn add fp-ts@^2.14.0`.

affects: >=0.7.0

gotchaPrior to version 0.6.12, the `string` parser (and other parsers built on deep recursion, such as `many` and `many1`) could exceed the JavaScript engine's recursion limit when attempting to parse very long input strings. This would result in a stack overflow error at runtime.

fix

Ensure you are using `parser-ts` version 0.6.12 or newer. This version (and subsequent ones) includes fixes that re-implement recursive parsers using `ChainRec` to prevent stack overflows on long inputs.

affects: <0.6.12

gotcha`parser-ts` is deeply integrated with `fp-ts` and leverages advanced functional programming concepts (e.g., Monads, Applicatives, Type Classes, `pipe` for composition). Developers unfamiliar with `fp-ts` or functional TypeScript may experience a steeper learning curve.

fix

Familiarize yourself with core `fp-ts` concepts, especially `Either`, `Option`, `pipe`, and basic type classes. The `fp-ts` documentation and examples are excellent resources for understanding the underlying patterns.

affects: >=0.1.0

Errors

Common errors & fixes

Error: Cannot find module 'fp-ts' or npm WARN peer dependency fp-ts@^2.14.0

The `fp-ts` library is a peer dependency of `parser-ts` and must be installed explicitly in your project's `node_modules`.

fix

Install `fp-ts` directly into your project: `npm install fp-ts@^2.14.0` or `yarn add fp-ts@^2.14.0`. Always check `parser-ts`'s `peerDependencies` for the exact compatible version range.

Property 'value' does not exist on type 'Either<ParseError, [unknown, string]>'.

The `run` function of a `Parser` returns a result wrapped in `fp-ts/Either`. This `Either` type represents either a `Left` (parse error) or a `Right` (successful parse). You must handle both cases and extract the value safely.

fix

Use `fp-ts/Either`'s combinators like `match`, `fold`, `isLeft`, or `isRight` to safely access the parsed value. For example: `E.match(() => console.error('Error'), ([value, _]) => console.log('Parsed:', value))(result)`.

Parsing consistently returns an `Left` error, even for seemingly valid input.

This typically indicates a subtle logic error in your parser combinator composition. Common issues include not handling whitespace, incorrect ordering of parsers (e.g., trying to parse a keyword after a more general identifier), or a parser consuming more input than intended.

fix

Debug your parser step-by-step. Use `P.run` with smaller, isolated parts of your input and parser definition to identify where the failure occurs. Pay close attention to optional parsers (`P.optional`) and sequence combinators (`P.apS`, `P.sequenceS`) to ensure they match your input's structure.

Upgrade

Version history

0.7.0latest on npm

Audit

Dependencies

fp-tsrequiredCore functional programming utilities and type classes required for parser definition and composition, including `Either`, `pipe`, and various Monad/Applicative instances.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/gcanti/parser-ts ↗

packagehttps://www.npmjs.com/package/parser-ts ↗