{"id":16170,"library":"parser-ts","title":"TypeScript Parser Combinators (parser-ts)","description":"`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.","status":"active","version":"0.7.0","language":"javascript","source_language":"en","source_url":"https://github.com/gcanti/parser-ts","tags":["javascript","typescript","parser-combinators","functional-programming","fp-ts"],"install":[{"cmd":"npm install parser-ts","lang":"bash","label":"npm"},{"cmd":"yarn add parser-ts","lang":"bash","label":"yarn"},{"cmd":"pnpm add parser-ts","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core functional programming utilities and type classes required for parser definition and composition, including `Either`, `pipe`, and various Monad/Applicative instances.","package":"fp-ts","optional":false}],"imports":[{"note":"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.","wrong":"import { string } from 'parser-ts'","symbol":"string","correct":"import { string } from 'parser-ts/string'"},{"note":"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.","wrong":"import { Parser } from 'parser-ts'","symbol":"Parser","correct":"import { Parser, run } from 'parser-ts/Parser'"},{"note":"`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`.","wrong":"import { pipe } from 'parser-ts'","symbol":"pipe","correct":"import { pipe } from 'fp-ts/function'"}],"quickstart":{"code":"import { pipe } from 'fp-ts/function';\nimport * as P from 'parser-ts/Parser';\nimport * as S from 'parser-ts/string';\nimport * as C from 'parser-ts/char';\nimport * as E from 'fp-ts/Either';\n\n// Define a parser for one or more digits, then convert to an integer\nconst integerParser = pipe(\n  S.recognize(C.many1(C.digit)), // `recognize` captures the matched string\n  P.map(parseInt)              // `map` transforms the parsed string to a number\n);\n\n// Define a parser for a literal comma character\nconst commaParser = C.char(',');\n\n// Define a parser for a list of integers separated by commas\n// `sepBy` applies `integerParser`, consuming `commaParser` in between\nconst commaSeparatedIntegersParser = pipe(\n  integerParser,\n  P.sepBy(commaParser)\n);\n\n// Helper function to run the parser and log results\nconst parseNumbers = (input: string) => {\n  console.log(`\\nAttempting to parse: \"${input}\"`);\n  const result = P.run(commaSeparatedIntegersParser, input);\n  E.match(\n    (error) => console.error('Parse Error:', error.message, 'at position', error.offset),\n    ([value, remaining]) => console.log('Parsed Value:', value, '| Remaining Input:', remaining.length === 0 ? 'None' : `\"${remaining}\"`) \n  )(result);\n};\n\n// Example Usage\nparseNumbers('1,2,3,4');\nparseNumbers('100');\nparseNumbers('1, 2, 3'); // Fails due to unexpected space\nparseNumbers('abc');\nparseNumbers('1,2,abc');","lang":"typescript","description":"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."},"warnings":[{"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`.","message":"Version 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.","severity":"breaking","affected_versions":">=0.7.0"},{"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.","message":"Prior 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.","severity":"gotcha","affected_versions":"<0.6.12"},{"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.","message":"`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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"The `fp-ts` library is a peer dependency of `parser-ts` and must be installed explicitly in your project's `node_modules`.","error":"Error: Cannot find module 'fp-ts' or npm WARN peer dependency fp-ts@^2.14.0"},{"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)`.","cause":"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.","error":"Property 'value' does not exist on type 'Either<ParseError, [unknown, string]>'."},{"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.","cause":"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.","error":"Parsing consistently returns an `Left` error, even for seemingly valid input."}],"ecosystem":"npm"}