{"id":13998617,"url":"https://github.com/JavaScriptRegenerated/yieldparser","last_synced_at":"2025-07-23T06:32:44.199Z","repository":{"id":72485617,"uuid":"315774639","full_name":"JavaScriptRegenerated/yieldparser","owner":"JavaScriptRegenerated","description":"Parse using JavaScript generator functions — it’s like components but for parsing!","archived":false,"fork":false,"pushed_at":"2024-02-09T14:35:50.000Z","size":524,"stargazers_count":71,"open_issues_count":19,"forks_count":2,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-08-10T19:17:28.111Z","etag":null,"topics":["generator-functions","javascript","parser","regular-expression","typescript"],"latest_commit_sha":null,"homepage":"https://regenerated.dev/article/parsing","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JavaScriptRegenerated.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2020-11-24T23:11:09.000Z","updated_at":"2024-07-21T18:01:57.000Z","dependencies_parsed_at":"2023-11-27T10:40:27.229Z","dependency_job_id":null,"html_url":"https://github.com/JavaScriptRegenerated/yieldparser","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JavaScriptRegenerated%2Fyieldparser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JavaScriptRegenerated%2Fyieldparser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JavaScriptRegenerated%2Fyieldparser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JavaScriptRegenerated%2Fyieldparser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JavaScriptRegenerated","download_url":"https://codeload.github.com/JavaScriptRegenerated/yieldparser/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227251576,"owners_count":17754044,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["generator-functions","javascript","parser","regular-expression","typescript"],"created_at":"2024-08-09T19:01:51.246Z","updated_at":"2024-11-30T01:30:22.417Z","avatar_url":"https://github.com/JavaScriptRegenerated.png","language":"TypeScript","readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003e👑 🌿 yieldparser\u003c/h1\u003e\n  \u003cp\u003eParse using composable generator functions. It’s like components for parsing.\u003c/p\u003e\n  \u003ca href=\"https://bundlephobia.com/result?p=yieldparser\"\u003e\n    \u003cimg src=\"https://badgen.net/bundlephobia/minzip/yieldparser@0.4.0\" alt=\"minified and gzipped size\"\u003e\n    \u003cimg src=\"https://badgen.net/bundlephobia/min/yieldparser@0.4.0\" alt=\"minified size\"\u003e\n    \u003cimg src=\"https://badgen.net/bundlephobia/dependency-count/yieldparser@0.4.0\" alt=\"zero dependencies\"\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n## Installation\n\n```console\nnpm add yieldparser\n```\n\n## Overview\n\nYieldparser parses a source chunk-by-chunk. You define a generator function that\nyields each chunk to be found. This chunk can be a `string`, a `RexExp`, or\nanother generator function. Your generator function receives replies from\nparsing that chunk, for example a regular expression would receive a reply with\nthe matches that were found. You then use this information to build a result:\nthe value that your generator function returns. This could be a simple value, or\nit could be an entire AST (abstract syntax tree).\n\nIf you yield an array of choices, then each choice is tested and the first one\nthat matches is used.\n\nIf your chunks don’t match the input string, then an error result is returned\nwith the remaining string and the chunk that it failed on. If it succeeds, then\na success result is returned with the return value of the generator function,\nand the remaining string (if there is anything remaining).\n\nRun `parse(input, yourGeneratorIterable)` to take an input string and parse into\na result.\n\nRun `invert(output, yourGeneratorIterable)` to take an expected result and map\nit back to a source string.\n\n## Examples\n\n- [Routes](#routes-parser)\n- [IP Address](#ip-address-parser)\n- [Maths expressions: `5 * 6 + 3`](src/math.test.ts)\n- [Basic CSS](#basic-css-parser)\n- Semver parser\n- Emoticons to Emoji\n- CSV\n- JSON\n- Cron\n- Markdown subset\n\n### Routes parser\n\nDefine a generator function for each route you have, and then define a top level\n`Routes` generator function. Then parse your path using `parse()`.\n\nYou can also map from a route object back to a path string using `invert()`.\n\n```typescript\nimport { invert, mustEnd, parse } from \"yieldparser\";\n\ntype Route =\n  | { type: \"home\" }\n  | { type: \"about\" }\n  | { type: \"terms\" }\n  | { type: \"blog\" }\n  | { type: \"blogArticle\"; slug: string };\n\nfunction* Home() {\n  yield \"/\";\n  yield mustEnd;\n  return { type: \"home\" } as Route;\n}\n\nfunction* About() {\n  yield \"/about\";\n  yield mustEnd;\n  return { type: \"about\" } as Route;\n}\n\nfunction* Terms() {\n  yield \"/legal\";\n  yield \"/terms\";\n  yield mustEnd;\n  return { type: \"terms\" } as Route;\n}\n\nfunction* blogPrefix() {\n  yield \"/blog\";\n}\n\nfunction* BlogHome() {\n  yield blogPrefix;\n  yield mustEnd;\n  return { type: \"blog\" };\n}\n\nfunction* BlogArticle() {\n  yield blogPrefix;\n  yield \"/\";\n  const [slug]: [string] = yield /^.+/;\n  return { type: \"blogArticle\", slug };\n}\n\nfunction* BlogRoutes() {\n  return yield [BlogHome, BlogArticle];\n}\n\nfunction* Routes() {\n  return yield [Home, About, Terms, BlogRoutes];\n}\n\nparse(\"/\", Routes()); // result: { type: \"home\" }, success: true, remaining: \"\" }\nparse(\"/about\", Routes()); // result: { type: \"about\" }, success: true, remaining: \"\" }\nparse(\"/legal/terms\", Routes()); // result: { type: \"terms\" }, success: true, remaining: \"\" }\nparse(\"/blog\", Routes()); // result: { type: \"blog\" }, success: true, remaining: \"\" }\nparse(\"/blog/happy-new-year\", Routes()); // result: { type: \"blogArticle\", slug: \"happy-new-year\" }, success: true, remaining: \"\" }\n\ninvert({ type: \"home\" }, Routes()); // \"/\"\ninvert({ type: \"about\" }, Routes()); // \"/about\"\ninvert({ type: \"terms\" }, Routes()); // \"/legal/terms\"\ninvert({ type: \"blog\" }, Routes()); // \"/blog\"\ninvert({ type: \"blogArticle\", slug: \"happy-new-year\" }, Routes()); // \"/blog/happy-new-year\"\n```\n\n### IP Address parser\n\n```typescript\nimport { mustEnd, parse } from \"yieldparser\";\n\nfunction* Digit() {\n  const [digit]: [string] = yield /^\\d+/;\n  const value = parseInt(digit, 10);\n  if (value \u003c 0 || value \u003e 255) {\n    return new Error(`Digit must be between 0 and 255, was ${value}`);\n  }\n  return value;\n}\n\nfunction* IPAddress() {\n  const first = yield Digit;\n  yield \".\";\n  const second = yield Digit;\n  yield \".\";\n  const third = yield Digit;\n  yield \".\";\n  const fourth = yield Digit;\n  yield mustEnd;\n  return [first, second, third, fourth];\n}\n\nparse(\"1.2.3.4\", IPAddress());\n/*\n{\n  success: true,\n  result: [1, 2, 3, 4],\n  remaining: '',\n}\n*/\n\nparse(\"1.2.3.256\", IPAddress());\n/*\n{\n  success: false,\n  failedOn: {\n    nested: [\n      {\n        yielded: new Error('Digit must be between 0 and 255, was 256'),\n      },\n    ],\n  },\n  remaining: '256',\n}\n*/\n```\n\n### Basic CSS parser\n\n```typescript\nimport { has, hasMore, parse } from \"yieldparser\";\n\ntype Selector = string;\ninterface Declaraction {\n  property: string;\n  value: string;\n}\ninterface Rule {\n  selectors: Array\u003cSelector\u003e;\n  declarations: Array\u003cDeclaraction\u003e;\n}\n\nconst whitespaceMay = /^\\s*/;\n\nfunction* PropertyParser() {\n  const [name]: [string] = yield /[-a-z]+/;\n  return name;\n}\n\nfunction* ValueParser() {\n  const [rawValue]: [string] = yield /(-?\\d+(rem|em|%|px|)|[-a-z]+)/;\n  return rawValue;\n}\n\nfunction* DeclarationParser() {\n  const name = yield PropertyParser;\n  yield whitespaceMay;\n  yield \":\";\n  yield whitespaceMay;\n  const rawValue = yield ValueParser;\n  yield whitespaceMay;\n  yield \";\";\n  return { name, rawValue };\n}\n\nfunction* RuleParser() {\n  const declarations: Array\u003cDeclaraction\u003e = [];\n\n  const [selector]: [string] = yield /(:root|[*]|[a-z][\\w]*)/;\n\n  yield whitespaceMay;\n  yield \"{\";\n  yield whitespaceMay;\n  while ((yield has(\"}\")) === false) {\n    yield whitespaceMay;\n    declarations.push(yield DeclarationParser);\n    yield whitespaceMay;\n  }\n\n  return { selector, declarations };\n}\n\nfunction* RulesParser() {\n  const rules = [];\n\n  yield whitespaceMay;\n  while (yield hasMore) {\n    rules.push(yield RuleParser);\n    yield whitespaceMay;\n  }\n  return rules;\n}\n\nconst code = `\n:root {\n  --first-var: 42rem;\n  --second-var: 15%;\n}\n\n* {\n  font: inherit;\n  box-sizing: border-box;\n}\n\nh1 {\n  margin-bottom: 1em;\n}\n`;\n\nparse(code, RulesParser());\n\n/*\n{\n  success: true,\n  result: [\n    {\n      selector: ':root',\n      declarations: [\n        {\n          name: '--first-var',\n          rawValue: '42rem',\n        },\n        {\n          name: '--second-var',\n          rawValue: '15%',\n        },\n      ],\n    },\n    {\n      selector: '*',\n      declarations: [\n        {\n          name: 'font',\n          rawValue: 'inherit',\n        },\n        {\n          name: 'box-sizing',\n          rawValue: 'border-box',\n        },\n      ],\n    },\n    {\n      selector: 'h1',\n      declarations: [\n        {\n          name: 'margin-bottom',\n          rawValue: '1em',\n        },\n      ],\n    },\n  ],\n  remaining: '',\n}\n*/\n```\n","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJavaScriptRegenerated%2Fyieldparser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FJavaScriptRegenerated%2Fyieldparser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJavaScriptRegenerated%2Fyieldparser/lists"}