-
-[](https://www.npmjs.com/package/unitas)
-[](https://coveralls.io/github/sovrin/unitas?branch=master)
-[](https://opensource.org/licenses/MIT)
-
-A lightweight, TypeScript-first parser combinator library for building expressive and composable parsers.
-
-## Features
-
-- **Parser Combinators**: Compose small parsers into complex ones using combinators like `many`, `choice`, `sequence`, and more
-- **Terminals**: Factory functions for common patterns (`char`, `string`, `regex`, etc.)
-- **Primitives**: Pre-built parser instances ready to use (`digit`, `letter`, `whitespace`, etc.)
-- **TypeScript**: Full TypeScript support with generic types and inference
-- **Tree-shakeable**: ESM-only with separate exports for `combinators`, `terminals`, `primitives`, and `utils`
-- **No dependencies**: Zero external runtime dependencies
-
-> **Note:** This library is in active development. The API may change before v1.0.0.
-
-## Installation
-
-```bash
-npm install unitas
-```
-
-## Quick Start
-
-**CSV parser** — parsing comma-separated values with quoted fields
-
-```typescript
-import { grammar, run } from 'unitas';
-import { choice, inner, separatedBy } from 'unitas/combinators';
-import { char, regex } from 'unitas/terminals';
-import { letters } from 'unitas/primitives';
-
-const csv = grammar({
- row: (p) => separatedBy(p.value, char(',')),
- value: (p) => choice(p.quoted, p.unquoted),
- quoted: () => inner(char('"'), regex(/^[^"]*/), char('"')),
- unquoted: () => letters,
-});
-
-run(csv.row, 'a,b,c'); // ['a', 'b', 'c']
-run(csv.row, '"a,b",c'); // ['a,b', 'c']
-```
-
-**JSON value parser** — parsing simple json values
-
-```typescript
-import { grammar, run } from 'unitas';
-import { choice, map, quoted } from 'unitas/combinators';
-import { string } from 'unitas/terminals';
-import { bool, digits, letters } from 'unitas/primitives';
-
-const json = grammar({
- value: (p) => choice(p.string, p.number, p.bool, p.null),
- string: () => quoted(letters),
- number: () => digits,
- bool: () => bool,
- null: () => map(string('null'), () => null),
-});
-
-run(json.value, '"hello"'); // 'hello'
-run(json.value, '42'); // 42
-run(json.value, 'true'); // true
-run(json.value, 'null'); // null
-```
-
-**Query string parser** — parsing URL query parameters
-
-```typescript
-import { grammar, run } from 'unitas';
-import { map, outer, separatedBy } from 'unitas/combinators';
-import { char } from 'unitas/terminals';
-import { letters } from 'unitas/primitives';
-
-type Query = {
- params: Record
-
-
-```typescript
-failure('unexpected input'); // { ok: false, error: 'unexpected input' }
-```
-
-
-failure — Creates a failed result with an optional error message.
-
-```typescript
-failure('unexpected input'); // { ok: false, error: 'unexpected input' }
-```
-
-
-
-
-```typescript
-type Math = {
- expr: number;
- term: number;
- value: number;
-};
-const g = grammar
-grammar — Creates a recursive grammar where rules can reference each other.
-
-```typescript
-type Math = {
- expr: number;
- term: number;
- value: number;
-};
-const g = grammar
-
-
-```typescript
-label(char('x'), 'letter x')(''); // { ok: false, error: 'expected letter x' }
-```
-
-
-label — Labels a parser with a custom error message on failure.
-
-```typescript
-label(char('x'), 'letter x')(''); // { ok: false, error: 'expected letter x' }
-```
-
-
-
-
-```typescript
-lazy(() => char('a'))('abc'); // { ok: true, value: 'a', remaining: 'bc' }
-```
-
-
-lazy — Defers parser creation, useful for recursive grammars.
-
-```typescript
-lazy(() => char('a'))('abc'); // { ok: true, value: 'a', remaining: 'bc' }
-```
-
-
-
-
-```typescript
-match(success('hello', ''), { success: (v) => v, failure: () => 'failed' }); // 'hello'
-```
-
-
-match — Pattern matching on a Result to handle success and failure cases.
-
-```typescript
-match(success('hello', ''), { success: (v) => v, failure: () => 'failed' }); // 'hello'
-```
-
-
-
-
-```typescript
-const memoDigits = memoize(digits);
-memoDigits('123'); // { ok: true, value: 123, remaining: '' }
-```
-
-
-memoize — Memoizes a parser to cache results by input string. Useful for expensive parsers and recursive grammars to avoid exponential backtracking.
-
-```typescript
-const memoDigits = memoize(digits);
-memoDigits('123'); // { ok: true, value: 123, remaining: '' }
-```
-
-
-
-
-```typescript
-create((input) => success('parsed', input.slice(6)))('hello world'); // { ok: true, value: 'parsed', remaining: 'world' }
-```
-
-
-parser — Creates a parser from a parser function.
-
-```typescript
-create((input) => success('parsed', input.slice(6)))('hello world'); // { ok: true, value: 'parsed', remaining: 'world' }
-```
-
-
-
-
-```typescript
-run(string('hello'), 'hello'); // 'hello'
-```
-
-
-run — Runs a parser and returns the value, throws on failure or unconsumed input.
-
-```typescript
-run(string('hello'), 'hello'); // 'hello'
-```
-
-
-
-
-```typescript
-success('hello', ' world'); // { ok: true, value: 'hello', remaining: ' world' }
-```
-
-
-
-## Terminals (`unitas/terminals`)
-
-**Terminals** are the basic building blocks that match specific parts of the input. They don't combine other parsers — they directly inspect the input string.
-
-success — Creates a successful result with a value and remaining input.
-
-```typescript
-success('hello', ' world'); // { ok: true, value: 'hello', remaining: ' world' }
-```
-
-
-
-
-```typescript
-char('A')('ABC'); // { ok: true, value: 'A', remaining: 'BC' }
-```
-
-
-char — Parse a specific character.
-
-```typescript
-char('A')('ABC'); // { ok: true, value: 'A', remaining: 'BC' }
-```
-
-
-
-
-```typescript
-charOf(['a', 'b', 'c'])('abc'); // { ok: true, value: 'a', remaining: 'bc' }
-```
-
-
-charOf — Parse any character from a set.
-
-```typescript
-charOf(['a', 'b', 'c'])('abc'); // { ok: true, value: 'a', remaining: 'bc' }
-```
-
-
-
-
-```typescript
-noneOf(['a', 'b', 'c'])('xyz'); // { ok: true, value: 'x', remaining: 'yz' }
-```
-
-
-noneOf — Parse any character not in the set.
-
-```typescript
-noneOf(['a', 'b', 'c'])('xyz'); // { ok: true, value: 'x', remaining: 'yz' }
-```
-
-
-
-
-```typescript
-oneOf(['hello', 'hell', 'help'])('helpful'); // { ok: true, value: 'help', remaining: 'ful' }
-```
-
-
-oneOf — Parse one string from a set of strings (longest match wins).
-
-```typescript
-oneOf(['hello', 'hell', 'help'])('helpful'); // { ok: true, value: 'help', remaining: 'ful' }
-```
-
-
-
-
-```typescript
-regex(/^\w+/)('hello world'); // { ok: true, value: 'hello', remaining: ' world' }
-```
-
-
-regex — Parse with a regular expression.
-
-```typescript
-regex(/^\w+/)('hello world'); // { ok: true, value: 'hello', remaining: ' world' }
-```
-
-
-
-
-```typescript
-satisfy((c) => c === 'a')('abc'); // { ok: true, value: 'a', remaining: 'bc' }
-```
-
-
-satisfy — Parse a character satisfying a predicate.
-
-```typescript
-satisfy((c) => c === 'a')('abc'); // { ok: true, value: 'a', remaining: 'bc' }
-```
-
-
-
-
-```typescript
-string('hello')('hello world'); // { ok: true, value: 'hello', remaining: ' world' }
-```
-
-
-string — Parse a specific string.
-
-```typescript
-string('hello')('hello world'); // { ok: true, value: 'hello', remaining: ' world' }
-```
-
-
-
-
-```typescript
-stringOf('abc')('abcdef'); // { ok: true, value: 'a', remaining: 'bcdef' }
-```
-
-
-stringOf — Parse first character that exists in string (like charOf but for a string).
-
-```typescript
-stringOf('abc')('abcdef'); // { ok: true, value: 'a', remaining: 'bcdef' }
-```
-
-
-
-
-```typescript
-take(3)('abcdef'); // { ok: true, value: 'abc', remaining: 'def' }
-```
-
-
-take — Take n characters.
-
-```typescript
-take(3)('abcdef'); // { ok: true, value: 'abc', remaining: 'def' }
-```
-
-
-
-
-```typescript
-takeWhile((c) => c !== 'x')('abcx'); // { ok: true, value: 'abc', remaining: 'x' }
-```
-
-
-takeWhile — Takes characters while the predicate returns true.
-
-```typescript
-takeWhile((c) => c !== 'x')('abcx'); // { ok: true, value: 'abc', remaining: 'x' }
-```
-
-
-
-
-```typescript
-token('let')('let x'); // { ok: true, value: 'let', remaining: 'x' }
-token('let')('let1'); // { ok: true, value: 'let', remaining: '1' }
-token('let')('let x'); // { ok: true, value: 'let', remaining: 'x' }
-```
-
-
-token — Parses a string as a token, skipping trailing whitespace. Unlike word, it does not enforce word boundaries - useful for parsing strings that might be followed by any character.
-
-```typescript
-token('let')('let x'); // { ok: true, value: 'let', remaining: 'x' }
-token('let')('let1'); // { ok: true, value: 'let', remaining: '1' }
-token('let')('let x'); // { ok: true, value: 'let', remaining: 'x' }
-```
-
-
-
-
-```typescript
-word('let')('let x'); // { ok: true, value: 'let', remaining: 'x' }
-word('let')('let1'); // { ok: false }
-word('if')('if (x)'); // { ok: true, value: 'if', remaining: '(x)' }
-```
-
-
-
-## Primitives (`unitas/primitives`)
-
-**Primitives** are pre-built parser instances ready to use. Unlike terminals which are factory functions (like `char('x')`), primitives are constants you can pass directly to combinators.
-
-word — Parses a specific word and ensures it is not followed by word characters. Use this when parsing keywords that should not be part of a longer identifier.
-
-```typescript
-word('let')('let x'); // { ok: true, value: 'let', remaining: 'x' }
-word('let')('let1'); // { ok: false }
-word('if')('if (x)'); // { ok: true, value: 'if', remaining: '(x)' }
-```
-
-
-
-
-```typescript
-alphaNum('a1'); // { ok: true, value: 'a', remaining: '1' }
-alphaNum('1a'); // { ok: true, value: '1', remaining: 'a' }
-```
-
-
-alphaNum — Parse a single alphanumeric character.
-
-```typescript
-alphaNum('a1'); // { ok: true, value: 'a', remaining: '1' }
-alphaNum('1a'); // { ok: true, value: '1', remaining: 'a' }
-```
-
-
-
-
-```typescript
-alphaNums('abc123'); // { ok: true, value: 'abc123', remaining: '' }
-```
-
-
-alphaNums — Parse one or more alphanumeric characters.
-
-```typescript
-alphaNums('abc123'); // { ok: true, value: 'abc123', remaining: '' }
-```
-
-
-
-
-```typescript
-anyChar('abc'); // { ok: true, value: 'a', remaining: 'bc' }
-```
-
-
-anyChar — Parse any single character.
-
-```typescript
-anyChar('abc'); // { ok: true, value: 'a', remaining: 'bc' }
-```
-
-
-
-
-```typescript
-bool('true'); // { ok: true, value: true, remaining: '' }
-bool('false'); // { ok: true, value: false, remaining: '' }
-bool('trueABC'); // { ok: true, value: true, remaining: 'ABC' }
-```
-
-
-bool — Parse a boolean literal.
-
-```typescript
-bool('true'); // { ok: true, value: true, remaining: '' }
-bool('false'); // { ok: true, value: false, remaining: '' }
-bool('trueABC'); // { ok: true, value: true, remaining: 'ABC' }
-```
-
-
-
-
-```typescript
-crlf('\r\nabc'); // { ok: true, value: '\r\n', remaining: 'abc' }
-```
-
-
-crlf — Parse CRLF line ending.
-
-```typescript
-crlf('\r\nabc'); // { ok: true, value: '\r\n', remaining: 'abc' }
-```
-
-
-
-
-```typescript
-digit('5abc'); // { ok: true, value: 5, remaining: 'abc' }
-```
-
-
-digit — Parse a single digit and return as number.
-
-```typescript
-digit('5abc'); // { ok: true, value: 5, remaining: 'abc' }
-```
-
-
-
-
-```typescript
-digits('123abc'); // { ok: true, value: 123, remaining: 'abc' }
-```
-
-
-digits — Parse one or more digits and return as number.
-
-```typescript
-digits('123abc'); // { ok: true, value: 123, remaining: 'abc' }
-```
-
-
-
-
-```typescript
-eof(''); // { ok: true, value: null, remaining: '' }
-```
-
-
-eof — Parse end of file (succeeds only on empty input).
-
-```typescript
-eof(''); // { ok: true, value: null, remaining: '' }
-```
-
-
-
-
-```typescript
-eol('\nabc'); // { ok: true, value: '\n', remaining: 'abc' }
-```
-
-
-eol — Parse end of line (\\n, \\r\\n, or EOF).
-
-```typescript
-eol('\nabc'); // { ok: true, value: '\n', remaining: 'abc' }
-```
-
-
-
-
-```typescript
-float('1.23'); // { ok: true, value: 1.23, remaining: '' }
-float('-2.5'); // { ok: true, value: -2.5, remaining: '' }
-float('1.23abc'); // { ok: true, value: 1.23, remaining: 'abc' }
-```
-
-
-float — Parse a floating point number.
-
-```typescript
-float('1.23'); // { ok: true, value: 1.23, remaining: '' }
-float('-2.5'); // { ok: true, value: -2.5, remaining: '' }
-float('1.23abc'); // { ok: true, value: 1.23, remaining: 'abc' }
-```
-
-
-
-
-```typescript
-hexDigit('fF9'); // { ok: true, value: 'f', remaining: 'F9' }
-```
-
-
-hexDigit — Parse a single hexadecimal digit.
-
-```typescript
-hexDigit('fF9'); // { ok: true, value: 'f', remaining: 'F9' }
-```
-
-
-
-
-```typescript
-hexDigits('deadbeef'); // { ok: true, value: 'deadbeef', remaining: '' }
-```
-
-
-hexDigits — Parse one or more hexadecimal digits.
-
-```typescript
-hexDigits('deadbeef'); // { ok: true, value: 'deadbeef', remaining: '' }
-```
-
-
-
-
-```typescript
-identifier('variable_name'); // { ok: true, value: 'variable_name', remaining: '' }
-```
-
-
-identifier — Parse an identifier — starts with letter or underscore, no leading digit, no hyphen.
-
-```typescript
-identifier('variable_name'); // { ok: true, value: 'variable_name', remaining: '' }
-```
-
-
-
-
-```typescript
-integer('42'); // { ok: true, value: 42, remaining: '' }
-integer('-7'); // { ok: true, value: -7, remaining: '' }
-integer('123abc'); // { ok: true, value: 123, remaining: 'abc' }
-```
-
-
-integer — Parse a signed integer.
-
-```typescript
-integer('42'); // { ok: true, value: 42, remaining: '' }
-integer('-7'); // { ok: true, value: -7, remaining: '' }
-integer('123abc'); // { ok: true, value: 123, remaining: 'abc' }
-```
-
-
-
-
-```typescript
-letter('abc'); // { ok: true, value: 'a', remaining: 'bc' }
-```
-
-
-letter — Parse a single letter.
-
-```typescript
-letter('abc'); // { ok: true, value: 'a', remaining: 'bc' }
-```
-
-
-
-
-```typescript
-letters('abc123'); // { ok: true, value: 'abc', remaining: '123' }
-```
-
-
-letters — Parse one or more letters.
-
-```typescript
-letters('abc123'); // { ok: true, value: 'abc', remaining: '123' }
-```
-
-
-
-
-```typescript
-line('hello\nworld'); // { ok: true, value: 'hello', remaining: '\nworld' }
-```
-
-
-line — Parse until end of line.
-
-```typescript
-line('hello\nworld'); // { ok: true, value: 'hello', remaining: '\nworld' }
-```
-
-
-
-
-```typescript
-literal('foo-bar'); // { ok: true, value: 'foo-bar', remaining: '' }
-literal('123abc'); // { ok: true, value: '123abc', remaining: '' }
-```
-
-
-literal — Parse a word-like value including hyphens.
-
-```typescript
-literal('foo-bar'); // { ok: true, value: 'foo-bar', remaining: '' }
-literal('123abc'); // { ok: true, value: '123abc', remaining: '' }
-```
-
-
-
-
-```typescript
-lowercase('abc'); // { ok: true, value: 'a', remaining: 'bc' }
-```
-
-
-lowercase — Parse a single lowercase letter.
-
-```typescript
-lowercase('abc'); // { ok: true, value: 'a', remaining: 'bc' }
-```
-
-
-
-
-```typescript
-lowercases('abcDEF'); // { ok: true, value: 'abc', remaining: 'DEF' }
-```
-
-
-lowercases — Parses one or more lowercase letters.
-
-```typescript
-lowercases('abcDEF'); // { ok: true, value: 'abc', remaining: 'DEF' }
-```
-
-
-
-
-```typescript
-nl('\ntext'); // { ok: true, value: '\n', remaining: 'text' }
-```
-
-
-nl — Parse a newline character.
-
-```typescript
-nl('\ntext'); // { ok: true, value: '\n', remaining: 'text' }
-```
-
-
-
-
-```typescript
-number('42'); // { ok: true, value: 42, remaining: '' }
-number('3.14'); // { ok: true, value: 3.14, remaining: '' }
-number('-7'); // { ok: true, value: -7, remaining: '' }
-number('-2.5'); // { ok: true, value: -2.5, remaining: '' }
-```
-
-
-number — Parse an integer or float.
-
-```typescript
-number('42'); // { ok: true, value: 42, remaining: '' }
-number('3.14'); // { ok: true, value: 3.14, remaining: '' }
-number('-7'); // { ok: true, value: -7, remaining: '' }
-number('-2.5'); // { ok: true, value: -2.5, remaining: '' }
-```
-
-
-
-
-```typescript
-octDigit('7abc'); // { ok: true, value: '7', remaining: 'abc' }
-```
-
-
-octDigit — Parse a single octal digit.
-
-```typescript
-octDigit('7abc'); // { ok: true, value: '7', remaining: 'abc' }
-```
-
-
-
-
-```typescript
-octDigits('0777abc'); // { ok: true, value: '0777', remaining: 'abc' }
-```
-
-
-octDigits — Parse one or more octal digits.
-
-```typescript
-octDigits('0777abc'); // { ok: true, value: '0777', remaining: 'abc' }
-```
-
-
-
-
-```typescript
-position('abc'); // { ok: true, value: 3, remaining: 'abc' }
-```
-
-
-position — Get current position (remaining input length).
-
-```typescript
-position('abc'); // { ok: true, value: 3, remaining: 'abc' }
-```
-
-
-
-
-```typescript
-rest('hello'); // { ok: true, value: 'hello', remaining: '' }
-```
-
-
-rest — Parse the rest of the input.
-
-```typescript
-rest('hello'); // { ok: true, value: 'hello', remaining: '' }
-```
-
-
-
-
-```typescript
-space(' abc'); // { ok: true, value: ' ', remaining: 'abc' }
-```
-
-
-space — Parse a single space character.
-
-```typescript
-space(' abc'); // { ok: true, value: ' ', remaining: 'abc' }
-```
-
-
-
-
-```typescript
-spaces(' abc'); // { ok: true, value: ' ', remaining: 'abc' }
-```
-
-
-spaces — Parse one or more space characters.
-
-```typescript
-spaces(' abc'); // { ok: true, value: ' ', remaining: 'abc' }
-```
-
-
-
-
-```typescript
-tab('\ttext'); // { ok: true, value: '\t', remaining: 'text' }
-```
-
-
-tab — Parse tab character.
-
-```typescript
-tab('\ttext'); // { ok: true, value: '\t', remaining: 'text' }
-```
-
-
-
-
-```typescript
-uppercase('ABC'); // { ok: true, value: 'A', remaining: 'BC' }
-```
-
-
-uppercase — Parses a single uppercase letter.
-
-```typescript
-uppercase('ABC'); // { ok: true, value: 'A', remaining: 'BC' }
-```
-
-
-
-
-```typescript
-uppercases('ABCdef'); // { ok: true, value: 'ABC', remaining: 'def' }
-```
-
-
-uppercases — Parses one or more uppercase letters.
-
-```typescript
-uppercases('ABCdef'); // { ok: true, value: 'ABC', remaining: 'def' }
-```
-
-
-
-
-```typescript
-whitespace(' abc'); // { ok: true, value: ' ', remaining: 'abc' }
-```
-
-
-whitespace — Parses a single whitespace character.
-
-```typescript
-whitespace(' abc'); // { ok: true, value: ' ', remaining: 'abc' }
-```
-
-
-
-
-```typescript
-whitespaces(' abc'); // { ok: true, value: ' ', remaining: 'abc' }
-```
-
-
-
-## Combinators (`unitas/combinators`)
-
-**Combinators** are functions that take one or more parsers and return a new parser. They are the "glue" that lets you compose complex parsers from simple ones.
-
-whitespaces — Parses one or more whitespace characters.
-
-```typescript
-whitespaces(' abc'); // { ok: true, value: ' ', remaining: 'abc' }
-```
-
-
-
-
-```typescript
-attempt(string('hello'))('hello world'); // { ok: true, value: 'hello', remaining: ' world' }
-```
-
-
-attempt — Attempt wraps a parser to handle backtracking on failure.
-
-```typescript
-attempt(string('hello'))('hello world'); // { ok: true, value: 'hello', remaining: ' world' }
-```
-
-
-
-
-```typescript
-bind(digits, (n) => take(n))('3abc'); // { ok: true, value: 'abc', remaining: '' }
-```
-
-
-bind — Chain parsers where the second parser depends on the first result.
-
-```typescript
-bind(digits, (n) => take(n))('3abc'); // { ok: true, value: 'abc', remaining: '' }
-```
-
-
-
-
-```typescript
-braced(string('hi'))('{hi}'); // { ok: true, value: 'hi', remaining: '' }
-```
-
-
-braced — Parse content surrounded by braces.
-
-```typescript
-braced(string('hi'))('{hi}'); // { ok: true, value: 'hi', remaining: '' }
-```
-
-
-
-
-```typescript
-bracketed(string('hi'))('[hi]'); // { ok: true, value: 'hi', remaining: '' }
-```
-
-
-bracketed — Parse content surrounded by brackets.
-
-```typescript
-bracketed(string('hi'))('[hi]'); // { ok: true, value: 'hi', remaining: '' }
-```
-
-
-
-
-```typescript
-chainLeft(digits, operation)('1+2+3'); // { ok: true, value: 6, remaining: '' }
-chainLeft(digits, operation)('10-3+2'); // { ok: true, value: 9, remaining: '' }
-```
-
-
-chainLeft — Chain left-associative operations (right-to-left for same precedence).
-
-```typescript
-chainLeft(digits, operation)('1+2+3'); // { ok: true, value: 6, remaining: '' }
-chainLeft(digits, operation)('10-3+2'); // { ok: true, value: 9, remaining: '' }
-```
-
-
-
-
-```typescript
-chainLeft1(digits, operation)('1+2+3'); // { ok: true, value: 6, remaining: '' }
-chainLeft1(digits, operation)('8/2*3'); // { ok: true, value: 12, remaining: '' }
-```
-
-
-chainLeft1 — Chain left-associative operations (fails on empty input).
-
-```typescript
-chainLeft1(digits, operation)('1+2+3'); // { ok: true, value: 6, remaining: '' }
-chainLeft1(digits, operation)('8/2*3'); // { ok: true, value: 12, remaining: '' }
-```
-
-
-
-
-```typescript
-chainRight(digits, operation)('2-1-1'); // { ok: true, value: 2, remaining: '' }
-chainRight(digits, operation)('4/2/2'); // { ok: true, value: 4, remaining: '' }
-```
-
-
-chainRight — Chain right-associative operations (right-to-left grouping).
-
-```typescript
-chainRight(digits, operation)('2-1-1'); // { ok: true, value: 2, remaining: '' }
-chainRight(digits, operation)('4/2/2'); // { ok: true, value: 4, remaining: '' }
-```
-
-
-
-
-```typescript
-chainRight1(digits, operation)('2-1-1'); // { ok: true, value: 2, remaining: '' }
-chainRight1(digits, operation)('4/2/2'); // { ok: true, value: 4, remaining: '' }
-```
-
-
-chainRight1 — Chain right-associative operations (fails on empty input).
-
-```typescript
-chainRight1(digits, operation)('2-1-1'); // { ok: true, value: 2, remaining: '' }
-chainRight1(digits, operation)('4/2/2'); // { ok: true, value: 4, remaining: '' }
-```
-
-
-
-
-```typescript
-choice(string('hello'), string('world'))('hello'); // { ok: true, value: 'hello', remaining: '' }
-```
-
-
-choice — Try each parser in order, return first success.
-
-```typescript
-choice(string('hello'), string('world'))('hello'); // { ok: true, value: 'hello', remaining: '' }
-```
-
-
-
-
-```typescript
-concat(many(letter))('abc123'); // { ok: true, value: 'abc', remaining: '123' }
-concat(many(letter), '-')('abc123'); // { ok: true, value: 'a-b-c', remaining: '123' }
-```
-
-
-concat — Join string array parser result into a single string.
-
-```typescript
-concat(many(letter))('abc123'); // { ok: true, value: 'abc', remaining: '123' }
-concat(many(letter), '-')('abc123'); // { ok: true, value: 'a-b-c', remaining: '123' }
-```
-
-
-
-
-```typescript
-consume(string('hello'))('hello world'); // { ok: true, value: null, remaining: ' world' }
-```
-
-
-consume — Consume input but discard the result (return null).
-
-```typescript
-consume(string('hello'))('hello world'); // { ok: true, value: null, remaining: ' world' }
-```
-
-
-
-
-```typescript
-endBy(string('item'), char(';'))('item;item;item;'); // { ok: true, value: ['item', 'item', 'item'], remaining: '' }
-```
-
-
-endBy — Zero or more items separated and ending with terminator.
-
-```typescript
-endBy(string('item'), char(';'))('item;item;item;'); // { ok: true, value: ['item', 'item', 'item'], remaining: '' }
-```
-
-
-
-
-```typescript
-endBy1(string('item'), char(';'))('item;item;item;'); // { ok: true, value: ['item', 'item', 'item'], remaining: '' }
-```
-
-
-endBy1 — One or more items separated and ending with terminator.
-
-```typescript
-endBy1(string('item'), char(';'))('item;item;item;'); // { ok: true, value: ['item', 'item', 'item'], remaining: '' }
-```
-
-
-
-
-```typescript
-exactly(char('a'), 3)('aaa'); // { ok: true, value: ['a', 'a', 'a'], remaining: '' }
-```
-
-
-exactly — Parse exactly n occurrences.
-
-```typescript
-exactly(char('a'), 3)('aaa'); // { ok: true, value: ['a', 'a', 'a'], remaining: '' }
-```
-
-
-
-
-```typescript
-first(sequence(char('a'), digit))('a1bc'); // { ok: true, value: 'a', remaining: 'bc' }
-```
-
-
-first — Extract the first element from a parser result array.
-
-```typescript
-first(sequence(char('a'), digit))('a1bc'); // { ok: true, value: 'a', remaining: 'bc' }
-```
-
-
-
-
-```typescript
-flag(string('*'))('*abc'); // { ok: true, value: true, remaining: 'abc' }
-flag(string('*'))('abc'); // { ok: true, value: false, remaining: 'abc' }
-```
-
-
-flag — Return true if parser succeeds, false otherwise. Always succeeds without consuming input on failure.
-
-```typescript
-flag(string('*'))('*abc'); // { ok: true, value: true, remaining: 'abc' }
-flag(string('*'))('abc'); // { ok: true, value: false, remaining: 'abc' }
-```
-
-
-
-
-```typescript
-fold(digit, [], (acc, d) => [...acc, d])('123'); // { ok: true, value: [1, 2, 3], remaining: '' }
-```
-
-
-fold — Parse zero or more and fold into a single value.
-
-```typescript
-fold(digit, [], (acc, d) => [...acc, d])('123'); // { ok: true, value: [1, 2, 3], remaining: '' }
-```
-
-
-
-
-```typescript
-fold1(digit, 0, (acc, d) => acc + d)('123'); // { ok: true, value: 6, remaining: '' }
-```
-
-
-fold1 — Parse one or more and fold into a single value.
-
-```typescript
-fold1(digit, 0, (acc, d) => acc + d)('123'); // { ok: true, value: 6, remaining: '' }
-```
-
-
-
-
-```typescript
-foldRight(digit, [], (acc, d) => [...acc, d])('123'); // { ok: true, value: [3, 2, 1], remaining: '' }
-```
-
-
-foldRight — Parse zero or more and fold right-to-left.
-
-```typescript
-foldRight(digit, [], (acc, d) => [...acc, d])('123'); // { ok: true, value: [3, 2, 1], remaining: '' }
-```
-
-
-
-
-```typescript
-foldRight1(digit, [], (acc, d) => [...acc, d])('123'); // { ok: true, value: [3, 2, 1], remaining: '' }
-```
-
-
-foldRight1 — Parse one or more and fold right-to-left.
-
-```typescript
-foldRight1(digit, [], (acc, d) => [...acc, d])('123'); // { ok: true, value: [3, 2, 1], remaining: '' }
-```
-
-
-
-
-```typescript
-fuse(char('a'), char('b'), char('c'))('abc'); // { ok: true, value: 'abc', remaining: '' }
-fuse(string('hello'), char(' '), string('world'))('hello world'); // { ok: true, value: 'hello world', remaining: '' }
-```
-
-
-fuse — Fuse multiple string parsers into a single one. The fused parser concatenates all string results.
-
-```typescript
-fuse(char('a'), char('b'), char('c'))('abc'); // { ok: true, value: 'abc', remaining: '' }
-fuse(string('hello'), char(' '), string('world'))('hello world'); // { ok: true, value: 'hello world', remaining: '' }
-```
-
-
-
-
-```typescript
-guard(true, string('hello'))('hello'); // { ok: true, value: 'hello', remaining: '' }
-guard(false, string('hello'))('hello'); // { ok: false }
-```
-
-
-guard — Conditionally apply parser based on a condition.
-
-```typescript
-guard(true, string('hello'))('hello'); // { ok: true, value: 'hello', remaining: '' }
-guard(false, string('hello'))('hello'); // { ok: false }
-```
-
-
-
-
-```typescript
-inner(char('('), string('hi'), char(')'))('(hi)'); // { ok: true, value: 'hi', remaining: '' }
-```
-
-
-inner — Extract inner value from surrounded content (like inner of braced).
-
-```typescript
-inner(char('('), string('hi'), char(')'))('(hi)'); // { ok: true, value: 'hi', remaining: '' }
-```
-
-
-
-
-```typescript
-interleaved(char('a'), char(','))('a,a,a'); // { ok: true, value: ['a', ',', 'a', ',', 'a'], remaining: '' }
-```
-
-
-interleaved — Parse items with interleaved separators.
-
-```typescript
-interleaved(char('a'), char(','))('a,a,a'); // { ok: true, value: ['a', ',', 'a', ',', 'a'], remaining: '' }
-```
-
-
-
-
-```typescript
-last(sequence(char('a'), char('b')))('ab'); // { ok: true, value: 'b', remaining: '' }
-```
-
-
-last — Extract the last element from a parser result array.
-
-```typescript
-last(sequence(char('a'), char('b')))('ab'); // { ok: true, value: 'b', remaining: '' }
-```
-
-
-
-
-```typescript
-left(string('hello'), string('world'))('helloworld'); // { ok: true, value: 'hello', remaining: '' }
-```
-
-
-left — Keep only the left result from a sequence.
-
-```typescript
-left(string('hello'), string('world'))('helloworld'); // { ok: true, value: 'hello', remaining: '' }
-```
-
-
-
-
-```typescript
-lexeme(string('hello'))('hello world'); // { ok: true, value: 'hello', remaining: 'world' }
-```
-
-
-lexeme — Parser that consumes trailing whitespace.
-
-```typescript
-lexeme(string('hello'))('hello world'); // { ok: true, value: 'hello', remaining: 'world' }
-```
-
-
-
-
-```typescript
-many(char('a'))('aaa'); // { ok: true, value: ['a', 'a', 'a'], remaining: '' }
-```
-
-
-many — Zero or more occurrences (never fails).
-
-```typescript
-many(char('a'))('aaa'); // { ok: true, value: ['a', 'a', 'a'], remaining: '' }
-```
-
-
-
-
-```typescript
-many1(char('a'))('aaa'); // { ok: true, value: ['a', 'a', 'a'], remaining: '' }
-```
-
-
-many1 — One or more occurrences (fails if no matches).
-
-```typescript
-many1(char('a'))('aaa'); // { ok: true, value: ['a', 'a', 'a'], remaining: '' }
-```
-
-
-
-
-```typescript
-manyAtLeast(char('a'), 2)('aaa'); // { ok: true, value: ['a', 'a', 'a'], remaining: '' }
-```
-
-
-manyAtLeast — Parse at least n occurrences.
-
-```typescript
-manyAtLeast(char('a'), 2)('aaa'); // { ok: true, value: ['a', 'a', 'a'], remaining: '' }
-```
-
-
-
-
-```typescript
-manyAtMost(char('a'), 2)('aaa'); // { ok: true, value: ['a', 'a'], remaining: 'a' }
-```
-
-
-manyAtMost — Parse at most n occurrences.
-
-```typescript
-manyAtMost(char('a'), 2)('aaa'); // { ok: true, value: ['a', 'a'], remaining: 'a' }
-```
-
-
-
-
-```typescript
-manyBetween(char('a'), 2, 3)('aaa'); // { ok: true, value: ['a', 'a', 'a'], remaining: '' }
-```
-
-
-manyBetween — Parse between min and max occurrences.
-
-```typescript
-manyBetween(char('a'), 2, 3)('aaa'); // { ok: true, value: ['a', 'a', 'a'], remaining: '' }
-```
-
-
-
-
-```typescript
-manyTill(char('a'), char('b'))('aaab'); // { ok: true, value: ['a', 'a', 'a'], remaining: '' }
-```
-
-
-manyTill — Parse zero or more until terminator matches.
-
-```typescript
-manyTill(char('a'), char('b'))('aaab'); // { ok: true, value: ['a', 'a', 'a'], remaining: '' }
-```
-
-
-
-
-```typescript
-map(string('hello'), (v) => v.toUpperCase())('hello'); // { ok: true, value: 'HELLO', remaining: '' }
-```
-
-
-map — Transform the parsed value.
-
-```typescript
-map(string('hello'), (v) => v.toUpperCase())('hello'); // { ok: true, value: 'HELLO', remaining: '' }
-```
-
-
-
-
-```typescript
-node('binop', { left: digits, op: char('+'), right: digits })('1+2'); // { ok: true, value: { type: 'binop', left: 1, op: '+', right: 2 }, remaining: '' }
-node('number', { value: digits })('123'); // { ok: true, value: { type: 'number', value: 123 }, remaining: '' }
-```
-
-
-node — Create a node from parser fields.
-
-```typescript
-node('binop', { left: digits, op: char('+'), right: digits })('1+2'); // { ok: true, value: { type: 'binop', left: 1, op: '+', right: 2 }, remaining: '' }
-node('number', { value: digits })('123'); // { ok: true, value: { type: 'number', value: 123 }, remaining: '' }
-```
-
-
-
-
-```typescript
-not(string('hello'))('world'); // { ok: true, value: null, remaining: 'world' }
-```
-
-
-not — Succeed if parser fails (without consuming input).
-
-```typescript
-not(string('hello'))('world'); // { ok: true, value: null, remaining: 'world' }
-```
-
-
-
-
-```typescript
-nth(sequence(char('a'), char('b'), char('c')), 1)('abc'); // { ok: true, value: 'b', remaining: '' }
-```
-
-
-nth — Extract the nth element from a parser result array.
-
-```typescript
-nth(sequence(char('a'), char('b'), char('c')), 1)('abc'); // { ok: true, value: 'b', remaining: '' }
-```
-
-
-
-
-```typescript
-optional(string('hello'))('hello'); // { ok: true, value: 'hello', remaining: '' }
-optional(string('hello'))('world'); // { ok: true, value: null, remaining: 'world' }
-```
-
-
-optional — Make parser optional (return null on failure, without consuming input).
-
-```typescript
-optional(string('hello'))('hello'); // { ok: true, value: 'hello', remaining: '' }
-optional(string('hello'))('world'); // { ok: true, value: null, remaining: 'world' }
-```
-
-
-
-
-```typescript
-optionalConsume(string('hello'))('hello world'); // { ok: true, value: undefined, remaining: ' world' }
-optionalConsume(string('hello'))('world'); // { ok: true, value: undefined, remaining: 'world' }
-```
-
-
-optionalConsume — Optionally consume input (always succeeds, returns void).
-
-```typescript
-optionalConsume(string('hello'))('hello world'); // { ok: true, value: undefined, remaining: ' world' }
-optionalConsume(string('hello'))('world'); // { ok: true, value: undefined, remaining: 'world' }
-```
-
-
-
-
-```typescript
-optionalSeparatedBy(digits, char(','))('1,2'); // { ok: true, value: [1, 2], remaining: '' }
-optionalSeparatedBy(digits, char(','))(',1'); // { ok: true, value: [null, 1], remaining: '' }
-optionalSeparatedBy(digits, char(','))('1,'); // { ok: true, value: [1], remaining: '' }
-```
-
-
-optionalSeparatedBy — Zero or more items separated by a separator, with optional null values.
-
-```typescript
-optionalSeparatedBy(digits, char(','))('1,2'); // { ok: true, value: [1, 2], remaining: '' }
-optionalSeparatedBy(digits, char(','))(',1'); // { ok: true, value: [null, 1], remaining: '' }
-optionalSeparatedBy(digits, char(','))('1,'); // { ok: true, value: [1], remaining: '' }
-```
-
-
-
-
-```typescript
-outer(char('('), string('hi'), char(')'))('(hi)'); // { ok: true, value: ['(', ')'], remaining: '' }
-```
-
-
-outer — Extract outer values from a sequence of 3 parsers (skip middle).
-
-```typescript
-outer(char('('), string('hi'), char(')'))('(hi)'); // { ok: true, value: ['(', ')'], remaining: '' }
-```
-
-
-
-
-```typescript
-padded(string('hi'))(' hi '); // { ok: true, value: 'hi', remaining: '' }
-```
-
-
-padded — Parse content with optional whitespace on both sides.
-
-```typescript
-padded(string('hi'))(' hi '); // { ok: true, value: 'hi', remaining: '' }
-```
-
-
-
-
-```typescript
-parenthesized(string('hi'))('(hi)'); // { ok: true, value: 'hi', remaining: '' }
-```
-
-
-parenthesized — Parse content surrounded by parentheses.
-
-```typescript
-parenthesized(string('hi'))('(hi)'); // { ok: true, value: 'hi', remaining: '' }
-```
-
-
-
-
-```typescript
-peek(string('hello'))('hello world'); // { ok: true, value: 'hello', remaining: 'hello world' }
-```
-
-
-peek — Parse without consuming input.
-
-```typescript
-peek(string('hello'))('hello world'); // { ok: true, value: 'hello', remaining: 'hello world' }
-```
-
-
-
-
-```typescript
-postfix(
- char('a'),
- map(char('!'), () => (x) => x),
-)('a!'); // { ok: true, value: 'a', remaining: '' }
-```
-
-
-postfix — Parse postfix operators (chains atom with operators that return functions).
-
-```typescript
-postfix(
- char('a'),
- map(char('!'), () => (x) => x),
-)('a!'); // { ok: true, value: 'a', remaining: '' }
-```
-
-
-
-
-```typescript
-prefix(
- map(char('-'), () => (x) => -x),
- digit,
-)('-5'); // { ok: true, value: -5, remaining: '' }
-```
-
-
-prefix — Parse prefix operators (like - in -5).
-
-```typescript
-prefix(
- map(char('-'), () => (x) => -x),
- digit,
-)('-5'); // { ok: true, value: -5, remaining: '' }
-```
-
-
-
-
-```typescript
-pure(42)('abc'); // { ok: true, value: 42, remaining: 'abc' }
-pure('ok')(''); // { ok: true, value: 'ok', remaining: '' }
-```
-
-
-pure — Always return a value without consuming input.
-
-```typescript
-pure(42)('abc'); // { ok: true, value: 42, remaining: 'abc' }
-pure('ok')(''); // { ok: true, value: 'ok', remaining: '' }
-```
-
-
-
-
-```typescript
-quoted(string('hello'))('"hello"'); // { ok: true, value: 'hello', remaining: '' }
-```
-
-
-quoted — Parse content surrounded by single or double quotes.
-
-```typescript
-quoted(string('hello'))('"hello"'); // { ok: true, value: 'hello', remaining: '' }
-```
-
-
-
-
-```typescript
-recover(string('hello'), 'default')('world'); // { ok: true, value: 'default', remaining: 'world' }
-```
-
-
-recover — Use fallback value when parser fails.
-
-```typescript
-recover(string('hello'), 'default')('world'); // { ok: true, value: 'default', remaining: 'world' }
-```
-
-
-
-
-```typescript
-right(string('hello'), string('world'))('helloworld'); // { ok: true, value: 'world', remaining: '' }
-```
-
-
-right — Keep only the right result from a sequence.
-
-```typescript
-right(string('hello'), string('world'))('helloworld'); // { ok: true, value: 'world', remaining: '' }
-```
-
-
-
-
-```typescript
-separatedBy(char('a'), char(','))('a,a,a'); // { ok: true, value: ['a', 'a', 'a'], remaining: '' }
-```
-
-
-separatedBy — Zero or more items separated by a separator.
-
-```typescript
-separatedBy(char('a'), char(','))('a,a,a'); // { ok: true, value: ['a', 'a', 'a'], remaining: '' }
-```
-
-
-
-
-```typescript
-separatedBy1(char('a'), char(','))('a,a,a'); // { ok: true, value: ['a', 'a', 'a'], remaining: '' }
-```
-
-
-separatedBy1 — One or more items separated by a separator.
-
-```typescript
-separatedBy1(char('a'), char(','))('a,a,a'); // { ok: true, value: ['a', 'a', 'a'], remaining: '' }
-```
-
-
-
-
-```typescript
-separatedEndBy(char('a'), char(';'))('a;a;a;'); // { ok: true, value: ['a', 'a', 'a'], remaining: '' }
-```
-
-
-separatedEndBy — Zero or more items separated by and ending with a terminator.
-
-```typescript
-separatedEndBy(char('a'), char(';'))('a;a;a;'); // { ok: true, value: ['a', 'a', 'a'], remaining: '' }
-```
-
-
-
-
-```typescript
-separatedEndBy1(char('a'), char(';'))('a;a;a;'); // { ok: true, value: ['a', 'a', 'a'], remaining: '' }
-```
-
-
-separatedEndBy1 — One or more items separated by and ending with a terminator.
-
-```typescript
-separatedEndBy1(char('a'), char(';'))('a;a;a;'); // { ok: true, value: ['a', 'a', 'a'], remaining: '' }
-```
-
-
-
-
-```typescript
-separatedUntil(char('a'), char(','), char(';'))('a,a,a;'); // { ok: true, value: ['a', 'a', 'a'], remaining: '' }
-```
-
-
-separatedUntil — Parse items separated by separator until terminator matches.
-
-```typescript
-separatedUntil(char('a'), char(','), char(';'))('a,a,a;'); // { ok: true, value: ['a', 'a', 'a'], remaining: '' }
-```
-
-
-
-
-```typescript
-sequence(char('a'), char('b'), char('c'))('abc'); // { ok: true, value: ['a', 'b', 'c'], remaining: '' }
-```
-
-
-sequence — Parse a sequence of parsers and return all results as an array.
-
-```typescript
-sequence(char('a'), char('b'), char('c'))('abc'); // { ok: true, value: ['a', 'b', 'c'], remaining: '' }
-```
-
-
-
-
-```typescript
-skip(char('a'), 2)('aabc'); // { ok: true, value: null, remaining: 'bc' }
-```
-
-
-skip — Skip a parser n times.
-
-```typescript
-skip(char('a'), 2)('aabc'); // { ok: true, value: null, remaining: 'bc' }
-```
-
-
-
-
-```typescript
-skipMany(char('a'))('aaabc'); // { ok: true, value: null, remaining: 'bc' }
-```
-
-
-skipMany — Skip zero or more occurrences (never fails, returns null).
-
-```typescript
-skipMany(char('a'))('aaabc'); // { ok: true, value: null, remaining: 'bc' }
-```
-
-
-
-
-```typescript
-skipMany1(char('a'))('aaabc'); // { ok: true, value: null, remaining: 'bc' }
-```
-
-
-skipMany1 — Skip one or more occurrences (fails if no matches).
-
-```typescript
-skipMany1(char('a'))('aaabc'); // { ok: true, value: null, remaining: 'bc' }
-```
-
-
-
-
-```typescript
-surrounded(char('['), string('hi'), char(']'))('[hi]'); // { ok: true, value: 'hi', remaining: '' }
-surrounded(char('a'), char('b'), char('c'))('abc'); // { ok: true, value: 'b', remaining: '' }
-```
-
-
-surrounded — Parse content surrounded by delimiters.
-
-```typescript
-surrounded(char('['), string('hi'), char(']'))('[hi]'); // { ok: true, value: 'hi', remaining: '' }
-surrounded(char('a'), char('b'), char('c'))('abc'); // { ok: true, value: 'b', remaining: '' }
-```
-
-
-
-
-```typescript
-unless(false, string('hello'))('hello'); // { ok: true, value: 'hello', remaining: '' }
-unless(true, string('hello'))('hello'); // { ok: true, value: null, remaining: 'hello' }
-```
-
-
-unless — Parse unless condition is true (inverse of guard).
-
-```typescript
-unless(false, string('hello'))('hello'); // { ok: true, value: 'hello', remaining: '' }
-unless(true, string('hello'))('hello'); // { ok: true, value: null, remaining: 'hello' }
-```
-
-
-
-
-```typescript
-until(char('a'), char('b'))('baaa'); // { ok: true, value: [], remaining: 'baaa' }
-until(char('a'), char('b'))('aaba'); // { ok: true, value: ['a', 'a'], remaining: 'ba' }
-```
-
-
-until — Parse until terminator matches (fails if terminator never matches).
-
-```typescript
-until(char('a'), char('b'))('baaa'); // { ok: true, value: [], remaining: 'baaa' }
-until(char('a'), char('b'))('aaba'); // { ok: true, value: ['a', 'a'], remaining: 'ba' }
-```
-
-
-
-
-```typescript
-validate(digit, (n) => n > 5)('7'); // { ok: true, value: 7, remaining: '' }
-validate(digit, (n) => n > 5)('3'); // { ok: false }
-```
-
-
-validate — Validate parsed value with a predicate.
-
-```typescript
-validate(digit, (n) => n > 5)('7'); // { ok: true, value: 7, remaining: '' }
-validate(digit, (n) => n > 5)('3'); // { ok: false }
-```
-
-
-
-
-```typescript
-value(string('true'), true)('true'); // { ok: true, value: true, remaining: '' }
-value(string('null'), null)('null'); // { ok: true, value: null, remaining: '' }
-```
-
-
-value — Replace parsed value with a constant.
-
-```typescript
-value(string('true'), true)('true'); // { ok: true, value: true, remaining: '' }
-value(string('null'), null)('null'); // { ok: true, value: null, remaining: '' }
-```
-
-
-
-
-```typescript
-when(flag(char('*')), pure('many'), pure('one'))('*rest'); // { ok: true, value: 'many', remaining: 'rest' }
-when(flag(char('*')), pure('many'), pure('one'))('abc'); // { ok: true, value: 'one', remaining: 'abc' }
-```
-
-
-
-## Utils (`unitas/utils`)
-
-**Utils** are utility functions for working with parser results, arrays, and function composition.
-
-when — Branch on a boolean parser result.
-
-```typescript
-when(flag(char('*')), pure('many'), pure('one'))('*rest'); // { ok: true, value: 'many', remaining: 'rest' }
-when(flag(char('*')), pure('many'), pure('one'))('abc'); // { ok: true, value: 'one', remaining: 'abc' }
-```
-
-
-
-
-```typescript
-filter([1, 2, 3])([1, 2, 3, 4, 5]); // [4, 5]
-filter([1, 2], true)([1, false, 3]); // [3]
-```
-
-
-filter — Exclude values from array.
-
-```typescript
-filter([1, 2, 3])([1, 2, 3, 4, 5]); // [4, 5]
-filter([1, 2], true)([1, false, 3]); // [3]
-```
-
-
-
-
-```typescript
-flatten()([1, [2, [3]]]); // [1, 2, [3]]
-flatten(2)([1, [2, [3]]]); // [1, 2, 3]
-```
-
-
-flatten — Flatten nested arrays.
-
-```typescript
-flatten()([1, [2, [3]]]); // [1, 2, [3]]
-flatten(2)([1, [2, [3]]]); // [1, 2, 3]
-```
-
-
-
-
-```typescript
-join()([1, 2, 3]); // '123'
-join('-')([1, 2, 3]); // '1-2-3'
-```
-
-
-join — Join array elements into a string.
-
-```typescript
-join()([1, 2, 3]); // '123'
-join('-')([1, 2, 3]); // '1-2-3'
-```
-
-
-
-
-```typescript
-pick(0, 2)(['a', 'b', 'c']); // ['a', 'c']
-pick(2, 4)(['a', 'b', 'c', 'd', 'e']); // ['c', 'e']
-```
-
-
-pick — Pick elements from an array by index.
-
-```typescript
-pick(0, 2)(['a', 'b', 'c']); // ['a', 'c']
-pick(2, 4)(['a', 'b', 'c', 'd', 'e']); // ['c', 'e']
-```
-
-
-
-
-```typescript
-pipe(lexeme)(letters)('xyz abc'); // { ok: true, value: 'xyz', remaining: 'abc' }
-```
-
-
-pipe — Pipe parser functions together.
-
-```typescript
-pipe(lexeme)(letters)('xyz abc'); // { ok: true, value: 'xyz', remaining: 'abc' }
-```
-
-
-
-
-```typescript
-pop()([1, 2, 3]); // 3
-```
-
-
-pop — Get the last element of an array.
-
-```typescript
-pop()([1, 2, 3]); // 3
-```
-
-
-
-
-```typescript
-shift()([1, 2, 3]); // 1
-```
-
-
-shift — Get the first element of an array.
-
-```typescript
-shift()([1, 2, 3]); // 1
-```
-
-
-
-
-```typescript
-spread()(1, 2, 3); // [1, 2, 3]
-```
-
-
-
-## License
-
-MIT
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7d52ae5
--- /dev/null
+++ b/README.md
@@ -0,0 +1,612 @@
+
+
+# unitas
+
+spread — Collect spread arguments into an array.
-
-```typescript
-spread()(1, 2, 3); // [1, 2, 3]
-```
-
-
+
+**Composing parsers into a unified whole.** A lightweight, TypeScript-first parser combinator library — write small parsers, combine them into big ones, get typed results back.
+
+[](https://www.npmjs.com/package/unitas)
+[](https://coveralls.io/github/sovrin/unitas?branch=master)
+[](https://opensource.org/licenses/MIT)
+
+```bash
+npm install unitas
+```
+
+```typescript
+import { grammar, run } from 'unitas';
+import { choice, inner, separatedBy } from 'unitas/combinators';
+import { char, regex } from 'unitas/terminals';
+import { letters } from 'unitas/primitives';
+
+const csv = grammar({
+ row: (p) => separatedBy(p.value, char(',')),
+ value: (p) => choice(p.quoted, p.unquoted),
+ quoted: () => inner(char('"'), regex(/^[^"]*/), char('"')),
+ unquoted: () => letters,
+});
+
+run(csv.row, 'a,b,c'); // ['a', 'b', 'c']
+run(csv.row, '"a,b",c'); // ['a,b', 'c']
+```
+
+- **Zero dependencies**, ESM-only, fully typed
+- **Tree-shakeable** — five entry points, import only what you touch
+- **126 composable exports** — grouped by what they do, indexed below
+- **Mutual recursion out of the box** via `grammar`, no forward declarations
+
+> **Note:** This library is in active development. The API may change before v1.0.0.
+
+## Contents
+
+- [Entry points](#entry-points)
+- [Which function do I need?](#which-function-do-i-need)
+- [Core concepts](#core-concepts)
+- [More examples](#more-examples)
+- [API index](#api-index)
+
+## Entry points
+
+Nothing is re-exported across entry points, so your bundler only ever sees what you import.
+
+| Import from | Contains |
+| -------------------- | ------------------------------------------------------------------ |
+| `unitas` | Types, `success`/`failure`, `run`, `grammar`, `lazy`, `memoize` |
+| `unitas/terminals` | Factories that match input directly — `char`, `string`, `regex`, … |
+| `unitas/primitives` | Ready-made parsers — `digit`, `letters`, `whitespace`, … |
+| `unitas/combinators` | Parsers that take parsers — `map`, `choice`, `sequence`, `many`, … |
+| `unitas/utils` | Helpers for `map` callbacks — `pick`, `join`, `pipe`, … |
+
+## Which function do I need?
+
+The library is broad on purpose: each function does one small thing, so grammars read like the format they parse. This table is the fastest way in — start from the intent, then look the name up in the [API index](#api-index).
+
+### Matching a single thing
+
+| I want to match… | Reach for |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| an exact character or string | `char`, `string` |
+| one of several strings (longest wins) | `oneOf` |
+| any character in / not in a set | `charOf`, `stringOf`, `noneOf` |
+| a character passing a predicate | `satisfy` |
+| a regular expression | `regex` |
+| a fixed number of characters, or a run | `take`, `takeWhile` |
+| a keyword not glued to more word characters | `word` |
+| a token, eating trailing whitespace | `token`, `lexeme` |
+| a value — no need to build it | `number`, `integer`, `float`, `bool`, `identifier`, `literal`, `line`, `rest` |
+| a character class | `letter`, `digit`, `alphaNum`, `hexDigit`, `octDigit`, `lowercase`, `uppercase`, `anyChar` |
+| whitespace or a line break | `whitespace`, `space`, `tab`, `nl`, `crlf`, `eol`, `eof` |
+
+Most primitives come in a singular and a plural form: `letter` matches one, `letters` matches a run of them. The same holds for `digit`/`digits`, `alphaNum`/`alphaNums`, `hexDigit`/`hexDigits`, `octDigit`/`octDigits`, `lowercase`/`lowercases`, `uppercase`/`uppercases`, `space`/`spaces` and `whitespace`/`whitespaces`. Need to know how much input is left? `position`.
+
+### Repeating
+
+| I want to… | Reach for |
+| ----------------------------------------- | ----------------------------------------------------- |
+| repeat zero or more / one or more times | `many`, `many1` |
+| repeat a bounded number of times | `exactly`, `manyAtLeast`, `manyAtMost`, `manyBetween` |
+| repeat with a separator between items | `separatedBy`, `separatedBy1`, `optionalSeparatedBy` |
+| …and allow a trailing separator | `separatedEndBy`, `separatedEndBy1` |
+| …where every item ends with the separator | `endBy`, `endBy1`, `interleaved` |
+| repeat until something else shows up | `manyTill`, `until`, `separatedUntil` |
+| repeat but throw the values away | `skip`, `skipMany`, `skipMany1` |
+| reduce the repetitions as I go | `fold`, `fold1`, `foldRight`, `foldRight1` |
+
+### Choosing and branching
+
+| I want to… | Reach for |
+| ------------------------------------------- | ------------------------------------------------ |
+| take the first alternative that matches | `choice` |
+| succeed either way | `optional`, `optionalConsume`, `recover`, `flag` |
+| succeed only when something _doesn't_ match | `not` |
+| gate on a boolean I already have | `guard`, `unless`, `when` |
+| look ahead without consuming input | `peek` |
+
+### Sequencing and pulling values out
+
+| I want to… | Reach for |
+| ------------------------------------------ | ------------------------------------------------------------------------ |
+| run parsers in order and keep every result | `sequence` |
+| keep only one side of a pair | `left`, `right` |
+| keep specific positions of a sequence | `first`, `last`, `nth`, `pick` |
+| drop the delimiters, keep the middle | `inner`, `outer` |
+| glue string results together | `concat`, `fuse`, `join` |
+| match content inside delimiters | `surrounded`, `parenthesized`, `braced`, `bracketed`, `quoted`, `padded` |
+
+### Shaping the result
+
+| I want to… | Reach for |
+| ------------------------------------------ | ----------------------------------------------------- |
+| transform the parsed value | `map`, `pipe` |
+| replace it with a constant | `value`, `pure`, `consume` |
+| build a typed AST node | `node` |
+| reject a value after parsing it | `validate` |
+| choose the next parser from the last value | `bind` |
+| tidy up arrays inside a `map` | `pick`, `filter`, `flatten`, `shift`, `pop`, `spread` |
+
+### Grammars, recursion and errors
+
+| I want to… | Reach for |
+| ------------------------------------------ | ------------------------------------------------------ |
+| let rules reference each other by name | `grammar` |
+| refer to a parser defined further down | `lazy` |
+| cache results and avoid exponential blowup | `memoize` |
+| attach a readable error message | `label` |
+| parse infix operators with precedence | `chainLeft`, `chainLeft1`, `chainRight`, `chainRight1` |
+| parse prefix / postfix operators | `prefix`, `postfix` |
+| handle both outcomes of a `Result` | `match` |
+
+## Core concepts
+
+### The `Parser` type
+
+A `Parser