{"id":50864807,"url":"https://github.com/lonnycorp/astroparse","last_synced_at":"2026-06-15T00:02:34.682Z","repository":{"id":329185466,"uuid":"1113905618","full_name":"lonnycorp/astroparse","owner":"lonnycorp","description":"A minimal, zero dependency, fully-typed parser combinator library","archived":false,"fork":false,"pushed_at":"2026-06-14T22:29:22.000Z","size":35,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-14T23:22:53.279Z","etag":null,"topics":["functional","parser","parser-combinators","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lonnycorp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-10T16:18:21.000Z","updated_at":"2026-06-14T22:28:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lonnycorp/astroparse","commit_stats":null,"previous_names":["tlonny/astroparse","lonnycorp/astroparse"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/lonnycorp/astroparse","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lonnycorp%2Fastroparse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lonnycorp%2Fastroparse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lonnycorp%2Fastroparse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lonnycorp%2Fastroparse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lonnycorp","download_url":"https://codeload.github.com/lonnycorp/astroparse/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lonnycorp%2Fastroparse/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34342089,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["functional","parser","parser-combinators","typescript"],"created_at":"2026-06-15T00:02:33.962Z","updated_at":"2026-06-15T00:02:34.671Z","avatar_url":"https://github.com/lonnycorp.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AstroParse\n\n![Check](https://github.com/lonnycorp/astroparse/actions/workflows/check.yml/badge.svg)\n![Release](https://github.com/lonnycorp/astroparse/actions/workflows/release.yml/badge.svg)\n\nA minimal, zero dependency, fully-typed parser combinator library.\n\n## Installation\n\n```bash\nnpm install @lonnycorp/astroparse\n```\n\n## Quick Look\n\n```typescript\nimport * as parser from \"@lonnycorp/astroparse\"\n\nconst parserName = new parser.Chain(\n    new parser.atom.Predicate(\n        new parser.atom.Character(),\n        c =\u003e /[a-zA-Z]/.test(c)\n            ? { success: true }\n            : { success: false, error: null }\n    )\n)\n    .try()\n    .many()\n    .map.value(chars =\u003e chars.join(\"\").toUpperCase())\n\n\nconst parserShout = new parser.Chain(\n    new parser.atom.Sequence([\n        new parser.common.Text(\"hello\"),\n        new parser.common.Whitespace(),\n        parserName\n    ])\n)\n    .map.value(([, , name]) =\u003e `Hello, ${name}!`)\n```\n\n```typescript\nconst result = parserShout.parse({ data: \"hello \\tsteven\", cursor: 0 })\n\nif (result.success) {\n    console.log(result.value) // Hello, STEVEN!\n} else {\n    console.error(result.error)\n}\n```\n\nThe same parser can be written with explicit atoms:\n\n```typescript\nconst parserNameExplicit = new parser.atom.map.Value(\n    new parser.atom.Many(\n        new parser.atom.Try(\n            new parser.atom.Predicate(\n                new parser.atom.Character(),\n                c =\u003e /[a-zA-Z]/.test(c)\n                    ? { success: true }\n                    : { success: false, error: null }\n            )\n        )\n    ),\n    (chars) =\u003e chars.join(\"\").toUpperCase()\n)\n\n\nconst parserShoutExplicit = new parser.atom.map.Value(\n    new parser.atom.Sequence([\n        new parser.common.Text(\"hello\"),\n        new parser.common.Whitespace(),\n        parserNameExplicit\n    ]),\n    ([,, name]) =\u003e `Hello, ${name}!`\n)\n```\n\n## Parser Definition\n\nA parser is simply a `Definition\u003cTValue, TError\u003e`: an object with a `parse` function that takes a `definition.Input` and returns a `definition.Result\u003cTValue, TError\u003e`.\n\n```typescript\nexport interface Definition\u003cTValue, TError\u003e {\n    parse(input: Input): Result\u003cTValue, TError\u003e\n}\n```\n\nA `definition.Input` is simply an object containing some string to be parsed, and a cursor describing how much of the string has been consumed.\n\n```typescript\nexport type Input = {\n    data: string\n    cursor: number\n}\n```\n\nA `definition.Result\u003cTValue, TError\u003e` is a discriminated union type describing either a successful or failed parse on a given input:\n\n```typescript\nexport type Result\u003cTValue, TError\u003e =\n    | ResultValue\u003cTValue\u003e\n    | ResultError\u003cTError\u003e\n```\n\nA successful parse will return a `definition.ResultValue\u003cTValue\u003e` object, containing a boolean (true) success discriminator, the value parsed from the input (of type `TValue`) and a new `definition.Input` reflecting any potential changes to input consumption:\n\n```typescript\nexport type ResultValue\u003cTValue\u003e = {\n    success: true\n    value: TValue,\n    input: Input\n}\n```\n\nA failed parse will return a `definition.ResultError\u003cTError\u003e` object, containing a boolean (false) success discriminator, the error returned by the parser (of type `TError`) and a new `definition.Input` reflecting any potential changes to input consumption:\n\n```typescript\nexport type ResultError\u003cTError\u003e = {\n    success: false\n    error: TError,\n    input: Input\n}\n```\n\nIt is possible to create your own custom parsers by directly implementing classes or objects that conform to the above spec. However, it is recommended that you instead construct custom parsers by composing the suite of atomic parsers provided by AstroParse where possible (it is a parser _combinator_ library after all!)\n\n## Atomic Parsers\n\nAstroParse provides a minimal (but arguably \"complete\") set of generic, atomic parsers:\n\n - `atom.Character`: consumes and returns the next input character. Errors if at the end of the input.\n - `atom.End`: complements `atom.Character` - returns a null if at the end of the input. Errors otherwise.\n - `atom.Value`: always \"parses\" a specified value without consuming any input.\n - `atom.Error`: always returns a specified error without consuming any input.\n - `atom.Predicate`: wraps an existing parser, checking the result against a predicate function and erroring if the predicate fails.\n - `atom.Try`: wraps an existing parser, backtracking any consumed input if the inner parser errors.\n - `atom.Peek`: wraps an existing parser, backtracking any consumed input.\n - `atom.Many`: wraps an existing parser, applying it repeatedly to produce an array of parsed values until an error is observed. The error will propagate if the erroring parser has consumed input.\n - `atom.Either`: wraps an array of parsers, attempting to parse each in order until a first value is successfully parsed. Any errors produced by sub-parsers will only propagate if input has been consumed.\n - `atom.Sequence`: wraps an array of parsers, attempting to parse each in sequence until all have successfully parsed. Any errors produced by sub-parsers are propagated straight away.\n - `atom.map.Value`: wraps a parser with a mapping function that transforms any parsed value whilst ignoring errors.\n - `atom.map.Error`: wraps a parser with a mapping function that transforms any errors whilst ignoring parsed values.\n\n## Common Parsers\n\nAstroParse also provides a very small set of common parsers where the behavior is broadly useful and intentionally opinionated:\n\n- `common.Text`: parses a specified text string exactly as-is. The string is treated atomically and will not consume input on failure.\n- `common.Whitespace`: parses a (potentially empty) region of whitespace. Will never return an error.\n- `common.SeparatedBy`: parses values separated by a separator parser. Parses zero or more by default, or one or more when `atLeastOne` is true.\n\n## Chaining\n\nFor more compact composition, `Chain` wraps any parser definition and returns another parser definition with fluent helpers. Common parsers use this internally where it keeps the composition readable.\n\n```typescript\nconst parserName = new parser.Chain(\n    new parser.atom.Predicate(\n        new parser.atom.Character(),\n        c =\u003e /[a-zA-Z]/.test(c)\n            ? { success: true }\n            : { success: false, error: null }\n    )\n)\n    .try()\n    .many()\n    .map.value(chars =\u003e chars.join(\"\").toUpperCase())\n```\n\nThe chain helpers mirror the most common unary wrappers: `map.value`, `map.error`, `try`, `peek`, and `many`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flonnycorp%2Fastroparse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flonnycorp%2Fastroparse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flonnycorp%2Fastroparse/lists"}