{"id":15755,"library":"peberminta","title":"peberminta","description":"peberminta is a simple, transparent, and highly generic parser combinator toolkit for TypeScript/JavaScript, currently at version 0.10.0 and appearing actively maintained. Its core design principle is to be agnostic to token types, options, and output, making it suitable for 'weird things with parsers' where traditional string-based parsers fall short. It is lightweight with zero dependencies and provides a comprehensive set of building blocks, enabling users to easily define custom parsing logic. A key differentiator is its emphasis on transparency, allowing full access to the parser state, and its opinionated stance on input, accepting only fixed arrays of tokens rather than streams. It does not include a built-in lexer, requiring users to supply their own. The library prioritizes practicality and clear typing, offering a robust foundation for complex parsing tasks without imposing strict constraints on input structures.","status":"active","version":"0.10.0","language":"javascript","source_language":"en","source_url":"https://github.com/mxxii/peberminta","tags":["javascript","parser","parser-combinators","parsec","typescript"],"install":[{"cmd":"npm install peberminta","lang":"bash","label":"npm"},{"cmd":"yarn add peberminta","lang":"bash","label":"yarn"},{"cmd":"pnpm add peberminta","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Primary import for core parser combinators. peberminta is designed for modern JavaScript environments, primarily ESM.","wrong":"const p = require('peberminta');","symbol":"p","correct":"import * as p from 'peberminta';"},{"note":"Import for character-specific parser building blocks, separate from the highly generic core.","wrong":"const pc = require('peberminta/char');","symbol":"pc","correct":"import * as pc from 'peberminta/char';"},{"note":"Importing types explicitly is good practice in TypeScript, though often inferred.","symbol":"Parser","correct":"import type { Parser } from 'peberminta';"}],"quickstart":{"code":"import * as p from 'peberminta';\nimport * as pc from 'peberminta/char';\n\n// Define a parser for a single hexadecimal digit (0-9, a-f, A-F)\nconst hexDigit = p.choice(\n  pc.digit, // 0-9\n  pc.charIn('abcdef'), // a-f\n  pc.charIn('ABCDEF')  // A-F\n);\n\n// Define a parser for a hex color code, e.g., #RRGGBB\nconst hexColorParser = p.seq(\n  pc.char('#'),\n  p.repeat(hexDigit, { min: 6, max: 6 })\n);\n\n// Function to parse and format the result\nconst parseHexColor = (input: string) => {\n  const tokens = input.split(''); // Simple tokenizer for char-based parsing\n  const result = hexColorParser({ tokens, offset: 0 });\n\n  if (result.type === 'Fail') {\n    return `Failed to parse: ${result.kind} at offset ${result.offset}`;\n  } else {\n    const hexChars = result.value[1].join(''); // Extract the hex digits\n    return `Successfully parsed hex color: #${hexChars}`;\n  }\n};\n\nconsole.log(parseHexColor('#AABBCC'));\nconsole.log(parseHexColor('#123xyz'));\nconsole.log(parseHexColor('ABCDEF'));","lang":"typescript","description":"Demonstrates defining and using basic parser combinators to parse a hexadecimal color string, including tokenization and result handling."},"warnings":[{"fix":"Ensure your input is fully tokenized into an array before passing it to any parser. If you need streaming capabilities, consider a different library or implement an external streaming tokenization layer.","message":"peberminta does not support streaming input; it expects a complete, fixed array of tokens. Users must tokenize their entire input upfront.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Refer to the `CHANGELOG.md` (linked in README) with each update and thoroughly test your parsing logic after upgrading to new minor versions.","message":"As a pre-1.0 package (current version 0.10.0), API stability is not guaranteed. Breaking changes may occur in minor versions without deprecation cycles.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Implement a custom tokenizer or use a separate lexing library (like `leac` mentioned in the README) to preprocess your input into an array of tokens before passing it to `peberminta` parsers.","message":"The core `peberminta` library is token-agnostic and does not provide an integrated lexer/tokenizer. Users must 'bring their own' lexer to convert raw input (e.g., strings) into a token array.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Prefer using `import` statements in projects configured for ESM. If strictly in a CommonJS environment, ensure Node.js is configured to handle ESM imports, or consider transpilation.","message":"peberminta is written with TypeScript and modern `import` syntax, suggesting a primary focus on ESM. While not explicitly stated as 'ESM-only', using `require()` in CommonJS environments might lead to import errors.","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":"Convert your project or the specific file to an ES Module by adding `\"type\": \"module\"` to your `package.json` or by changing the file extension to `.mjs`. Then use `import * as p from 'peberminta';`.","cause":"Attempting to import peberminta using `require()` in a CommonJS module, but the package is an ES Module.","error":"ERR_REQUIRE_ESM: require() of ES Module .../node_modules/peberminta/dist/index.js from ... not supported."},{"fix":"Ensure that the `tokens` array in your `PState` matches the expected token type of your parser. If your parser expects `char` tokens (strings of length 1), make sure your `tokens` array contains `string[]`. Explicitly typing `PState<YourTokenType>` can help resolve ambiguities.","cause":"Mismatch in the generic type parameters for `PState` (Parser State) or `Parser` functions, often when the token type is not explicitly handled or inferred correctly.","error":"Argument of type '{ tokens: string[]; offset: number; }' is not assignable to parameter of type 'PState<unknown>'"},{"fix":"Always check the `type` property of the `ParseResult` object. Use a conditional check like `if (result.type === 'Ok') { /* access result.value */ } else { /* handle error */ }`.","cause":"Directly trying to access `value` or other properties on a `ParseResult` without checking its `type` property, which could be 'Fail' if parsing fails.","error":"Type 'Fail' is not assignable to type 'Ok<TOutput, TToken>'"},{"fix":"Review the documentation and type definitions for the specific combinator function. Ensure all required arguments are present and their types (especially the generic `Parser<TOutput, TToken>`) match the expected signature. For example, `p.seq` expects an array of parsers.","cause":"Incorrect number or type of arguments passed to a parser combinator function, or a combinator expects a different parser signature than provided.","error":"No overload matches this call."}],"ecosystem":"npm"}