[sovrin]

Parsers took a sliced suffix of the input, so nothing in the system knew where it was in the original source. Position wasn't being withheld — it didn't exist. position returned the remaining length, and 50 of the 52 failure sites passed no message, because there was nothing useful to say.

before : Error: Not all input consumed: ",b=x,c=3"

after  : ParseError: 1:7 expected digit, found 'x'
           1 | a=1,b=x,c=3
             |       ^

What changed

A Parser<T> now reads from an offset and never slices:

type Parser<T> = (input: string, index?: number, ctx?: Context) => Result<T>;
type Success<T> = { ok: true; value: T; index: number };
type Failure = { ok: false; index: number; expected: readonly string[] };

Both new arguments are optional, so myParser('input') still works — test/quickstart.test.ts passed through the entire refactor untouched.

ctx is a per-parse context holding the furthest offset any branch reached and what was wanted there. It only moves forward, so backtracking can't lose it, and it's written only on the failure path. That's what makes the message point at the real mistake: separatedBy succeeds at 1:4 with one pair, so without it the error would read 1:4 expected end of input — technically true, and pointing at the wrong character.

choice unions the expectations of every alternative tried at an offset:

1:1 expected 'const', 'let' or 'var', found 'l'
  1 | lot x
    | ^

Falling out of the offsets

• parse returns a failure with line, column and expectations instead of throwing; run throws a ParseError carrying the same.
• grammar names left-recursive rules instead of overflowing the stack.
• memoize keys on an offset, so entries are cheap and are dropped when a different input is parsed.
• regex matches with a sticky pattern, anchored by construction; a leading ^ is redundant and stripped.
• position reports the offset from the start, so it pairs with locate to give a parsed node a source span.

Performance

Median ms, invoked as run does so tracking cost is included:

benchmark	master	this branch
many(char) 200k	4.63	2.89
many(regex) 200k	10.23	7.97
separatedBy(digits) 20k	5.71	5.26
kv pairs 10k	5.56	5.25
many(choice ×3) 20k	8.51	8.53
bracketed list 10k	5.94	2.27

Faster or tied everywhere. Nothing allocates a slice per step any more.

The first draft (8f4c8aa's parent) carried the trace on every Result and threaded it with a merge — what Parsec and Parsimmon do. It worked, but it allocated on every step that backtracked (separatedBy 20k went to 13.29ms, 2.3× master) and put two bookkeeping fields on Success, so every documented example grew a trace — including successes, where an expected on a completed parse reads as a contradiction. Moving it to a context fixed both.

Packaging

Each entry point was built separately, inlining core into four of the five bundles. Importing from more than one entry — how the library is meant to be used, and what the quick start does — shipped that code several times over. One build with five entries emits it once:

	before	after
quickstart's four entries	16 967 B	14 797 B
total shipped	17 357 B	15 187 B
app importing char + many	1 232 B	850 B

A single unbundled entry costs +660 B, since a chunk is all-or-nothing. Anyone who bundles comes out ahead: the duplicate copies were exactly what a tree-shaker could never remove.

The one sharp edge

A combinator that fails to pass ctx on still parses correctly and only produces a worse message — nothing an ordinary test would catch. src/core/propagation.test.ts scans every parser call site in combinators/, primitives/ and terminals/ and picks up new files on its own.

It earned its keep immediately: it caught not leaking the failure it exists to swallow. not and label now isolate their inner context, and memoize keeps each entry's trace so a cache hit still contributes to the message.

Breaking changes

Success.remaining → Success.index; Failure.error → index/expected. success(value, remaining) → success(value, index), failure(message) → failure(ctx, index, ...expected). run throws a ParseError rather than a generic Error, match's failure branch receives (index, expected), and position returns an offset rather than the remaining length.

Composing the built-in parsers needs no change. See Migrating from 0.2.x in the README for the full table.

Verification

258 test files, 1324 tests, no type errors, lint clean, five bundles build. attw unchanged — 5 green on node16 (from ESM) and bundler, same expected CJS reds for an ESM-only package.

Checked against the published artifact rather than just src: imported all five entries from dist/ and ran a real parse — messages correct, instanceof ParseError works across the chunk boundary. Every error example in the README is executed and matches verbatim.

Version bumped to 0.3.0.

🤖 Generated with Claude Code