@futpib/parser 1.0.1 → 1.0.2

package/build/inputReaderState.js

@@ -0,0 +1,16 @@
+export const inputReaderStateCompanion = {
+    isDone({ unconsumedBufferedSequences, unbufferedSequences, }) {
+        return (unconsumedBufferedSequences.length === 0
+            && unbufferedSequences === undefined);
+    },
+    async *toRemainingInputAsyncIterator({ unconsumedBufferedSequences, unbufferedSequences, }) {
+        yield* unconsumedBufferedSequences;
+        if (unbufferedSequences !== undefined) {
+            yield* {
+                [Symbol.asyncIterator]() {
+                    return unbufferedSequences;
+                },
+            };
+        }
+    },
+};

package/build/inspect.d.ts

@@ -0,0 +1 @@
+export declare const inspect: (value: unknown) => string;

package/build/inspect.js

@@ -0,0 +1,7 @@
+import { inspect as nodeInspect } from 'node:util';
+export const inspect = (value) => {
+    if (value instanceof Uint8Array) {
+        value = Buffer.from(value);
+    }
+    return nodeInspect(value);
+};

package/build/javaKeyStoreParser.test.js

@@ -2,12 +2,12 @@ import test from 'ava';
 import { uint8ArrayParserInputCompanion } from './parserInputCompanion.js';
 import { runParser } from './parser.js';
 import { javaKeyStoreParser } from './javaKeyStoreParser.js';
+import { fetchCid } from './fetchCid.js';
 for (const javaKeyStoreCid of [
     'bafkreig6k53b6p7bdvfjxc5mcb4qv3mffqls5ymqerxkqd6ih2xy5cs3n4',
 ]) {
     test('javaKeyStore ' + javaKeyStoreCid, async (t) => {
-        const javaKeyStoreResponse = await fetch('https://ipfs.io/ipfs/' + javaKeyStoreCid);
-        const javaKeyStoreStream = javaKeyStoreResponse.body;
+        const javaKeyStoreStream = await fetchCid(javaKeyStoreCid);
         const actual = await runParser(javaKeyStoreParser, javaKeyStoreStream, uint8ArrayParserInputCompanion, {
             errorJoinMode: 'all',
         });

package/build/jsonParser.d.ts

@@ -1,3 +1,5 @@
 import { type JsonValue } from 'type-fest';
 import { type Parser } from './parser.js';
+export declare const jsonStringParser: Parser<string, string>;
+export declare const jsonNumberParser: Parser<number, string>;
 export declare const jsonValueParser: Parser<JsonValue, string>;

package/build/jsonParser.js

@@ -10,6 +10,7 @@ import { createArrayParser } from './arrayParser.js';
 import { createParserAccessorParser } from './parserAccessorParser.js';
 import { createElementParser } from './elementParser.js';
 import { parserCreatorCompose } from './parserCreatorCompose.js';
+import { createSeparatedArrayParser } from './separatedArrayParser.js';
 const whitespaceParser = createArrayParser(createUnionParser([
     createExactSequenceParser(' '),
     createExactSequenceParser('\t'),
@@ -47,11 +48,11 @@ const jsonStringCharacterParser = createDisjunctionParser([
         return character;
     })(),
 ]);
-const jsonStringParser = promiseCompose(createTupleParser([
+export const jsonStringParser = promiseCompose(createTupleParser([
     createExactSequenceParser('"'),
     promiseCompose(createTerminatedArrayParser(jsonStringCharacterParser, createExactSequenceParser('"')), ([characters]) => characters.join('')),
 ]), ([, string]) => string);
-const jsonNumberParser = parserCreatorCompose(() => createArrayParser(parserCreatorCompose(() => elementParser, character => async (parserContext) => {
+export const jsonNumberParser = parserCreatorCompose(() => createArrayParser(parserCreatorCompose(() => elementParser, character => async (parserContext) => {
     parserContext.invariant((character === '-'
         || (character >= '0' && character <= '9')
         || character === '.'
@@ -113,18 +114,14 @@ const jsonObjectParser = promiseCompose(createTupleParser([
 const jsonArrayParser = promiseCompose(createTupleParser([
     createExactSequenceParser('['),
     whitespaceParser,
-    promiseCompose(createTerminatedArrayParser(createDisjunctionParser([
-        promiseCompose(createTupleParser([
-            createParserAccessorParser(() => jsonValueParser),
-            whitespaceParser,
-            createExactSequenceParser(','),
-            whitespaceParser,
-        ]), ([value]) => value),
-        promiseCompose(createTupleParser([
-            createParserAccessorParser(() => jsonValueParser),
-            whitespaceParser,
-        ]), ([value]) => value),
-    ]), createExactSequenceParser(']')), ([values]) => values),
+    createSeparatedArrayParser(createParserAccessorParser(() => jsonValueParser), createTupleParser([
+        whitespaceParser,
+        createExactSequenceParser(','),
+        whitespaceParser,
+    ])),
+    whitespaceParser,
+    createExactSequenceParser(']'),
+    whitespaceParser,
 ]), ([_bracket, _whitespace, values]) => values);
 export const jsonValueParser = createUnionParser([
     jsonObjectParser,

package/build/leb128Parser.d.ts

@@ -0,0 +1,7 @@
+import { Parser } from "./parser.js";
+export declare const uleb128Parser: Parser<bigint, Uint8Array>;
+export declare const sleb128Parser: Parser<bigint, Uint8Array>;
+export declare const uleb128NumberParser: Parser<number, Uint8Array>;
+export declare const sleb128NumberParser: Parser<number, Uint8Array>;
+export declare const uleb128UnsafeNumberParser: Parser<number, Uint8Array>;
+export declare const sleb128UnsafeNumberParser: Parser<number, Uint8Array>;

package/build/leb128Parser.js

@@ -0,0 +1,82 @@
+export const uleb128Parser = async (parserContext) => {
+    let leastSignificantValueBitIndex = 0n;
+    let value = 0n;
+    while (true) {
+        const byte = await parserContext.read(0);
+        const byteValue = BigInt(byte & 0b01111111);
+        const byteNotLast = BigInt(byte & 0b10000000);
+        value |= byteValue << leastSignificantValueBitIndex;
+        if (byteNotLast) {
+            leastSignificantValueBitIndex += 7n;
+            continue;
+        }
+        break;
+    }
+    return value;
+};
+export const sleb128Parser = async (parserContext) => {
+    let value = 0n;
+    let leastSignificantValueBitIndex = 0n;
+    while (true) {
+        const byte = await parserContext.read(0);
+        const byteValue = BigInt(byte & 0b01111111);
+        const byteNotLast = BigInt(byte & 0b10000000);
+        value |= byteValue << leastSignificantValueBitIndex;
+        leastSignificantValueBitIndex += 7n;
+        if (byteNotLast) {
+            continue;
+        }
+        const mostSignificantInputBit = byte & 0b01000000;
+        if (mostSignificantInputBit) {
+            value |= (~0n << leastSignificantValueBitIndex);
+        }
+        break;
+    }
+    return value;
+};
+export const uleb128NumberParser = async (parserContext) => {
+    const value = await uleb128Parser(parserContext);
+    parserContext.invariant(Number(value) <= Number.MAX_SAFE_INTEGER, 'Value is too large to be represented as a number: %s', value);
+    return Number(value);
+};
+export const sleb128NumberParser = async (parserContext) => {
+    const value = await sleb128Parser(parserContext);
+    parserContext.invariant(Number(value) >= Number.MIN_SAFE_INTEGER && Number(value) <= Number.MAX_SAFE_INTEGER, 'Value is too large to be represented as a number: %s', value);
+    return Number(value);
+};
+export const uleb128UnsafeNumberParser = async (parserContext) => {
+    let leastSignificantValueBitIndex = 0;
+    let value = 0;
+    while (true) {
+        const byte = await parserContext.read(0);
+        const byteValue = byte & 0b01111111;
+        const byteNotLast = byte & 0b10000000;
+        value |= byteValue << leastSignificantValueBitIndex;
+        if (byteNotLast) {
+            leastSignificantValueBitIndex += 7;
+            continue;
+        }
+        break;
+    }
+    return value;
+};
+export const sleb128UnsafeNumberParser = async (parserContext) => {
+    let value = 0;
+    let leastSignificantValueBitIndex = 0;
+    while (true) {
+        const byte = await parserContext.read(0);
+        const byteValue = byte & 0b01111111;
+        const byteNotLast = byte & 0b10000000;
+        value |= byteValue << leastSignificantValueBitIndex;
+        leastSignificantValueBitIndex += 7;
+        if (byteNotLast) {
+            continue;
+        }
+        const mostSignificantInputBit = byte & 0b01000000;
+        if (leastSignificantValueBitIndex < 32 && mostSignificantInputBit) {
+            value |= (~0 << leastSignificantValueBitIndex);
+        }
+        break;
+    }
+    return value;
+};

package/build/leb128Parser.test.js

@@ -0,0 +1,107 @@
+import { testProp, fc } from '@fast-check/ava';
+import test from 'ava';
+// @ts-expect-error
+import leb128 from 'leb128';
+import { uint8ArrayParserInputCompanion } from './parserInputCompanion.js';
+import { runParser } from './parser.js';
+import { uleb128Parser, sleb128Parser, uleb128NumberParser, sleb128NumberParser } from './leb128Parser.js';
+test('sleb128, uleb128, uleb128p1', async (t) => {
+    for (const [input, expectedSleb128, expectedUleb128,] of [
+        [Buffer.from('00', 'hex'), 0n, 0n],
+        [Buffer.from('01', 'hex'), 1n, 1n],
+        [Buffer.from('7f', 'hex'), -1n, 127n],
+        [Buffer.from('807f', 'hex'), -128n, 16256n],
+    ]) {
+        const actualSleb128 = await runParser(sleb128Parser, input, uint8ArrayParserInputCompanion);
+        const actualUleb128 = await runParser(uleb128Parser, input, uint8ArrayParserInputCompanion);
+        t.is(actualSleb128, expectedSleb128, 'sleb128');
+        t.is(actualUleb128, expectedUleb128, 'uleb128');
+    }
+    for (const [input, expectedUleb128,] of [
+        [new Uint8Array([2]), 2n],
+        [new Uint8Array([127]), 127n],
+        [new Uint8Array([0 + 0x80, 1]), 128n],
+        [new Uint8Array([1 + 0x80, 1]), 129n],
+        [new Uint8Array([57 + 0x80, 100]), 12857n],
+    ]) {
+        const actualUleb128 = await runParser(uleb128Parser, input, uint8ArrayParserInputCompanion);
+        t.is(actualUleb128, expectedUleb128, 'uleb128');
+    }
+    for (const [input, expectedSleb128,] of [
+        [new Uint8Array([2]), 2n],
+        [new Uint8Array([0x7e]), -2n],
+        [new Uint8Array([127 + 0x80, 0]), 127n],
+        [new Uint8Array([1 + 0x80, 0x7f]), -127n],
+        [new Uint8Array([0 + 0x80, 1]), 128n],
+        [new Uint8Array([0 + 0x80, 0x7f]), -128n],
+        [new Uint8Array([1 + 0x80, 1]), 129n],
+        [new Uint8Array([0x7f + 0x80, 0x7e]), -129n],
+    ]) {
+        const actualSleb128 = await runParser(sleb128Parser, input, uint8ArrayParserInputCompanion);
+        t.is(actualSleb128, expectedSleb128, 'sleb128');
+    }
+});
+testProp('uleb128NumberParser on small number', [
+    fc.nat(),
+], async (t, natural) => {
+    const uleb128 = leb128.unsigned.encode(natural);
+    const actualUleb128 = await runParser(uleb128NumberParser, uleb128, uint8ArrayParserInputCompanion);
+    t.is(actualUleb128, natural, 'uleb128');
+}, {
+    verbose: true,
+});
+testProp('sleb128NumberParser on small number', [
+    fc.integer(),
+], async (t, integer) => {
+    const sleb128 = leb128.signed.encode(integer);
+    const actualSleb128 = await runParser(sleb128NumberParser, sleb128, uint8ArrayParserInputCompanion);
+    t.is(actualSleb128, integer, 'sleb128');
+}, {
+    verbose: true,
+});
+// TODO?
+testProp.skip('uleb128NumberParser on large number', [
+    fc.maxSafeNat(),
+], async (t, natural) => {
+    const uleb128 = leb128.unsigned.encode(natural);
+    if (natural > (2 ** 32) - 1) {
+        await t.throwsAsync(() => runParser(uleb128NumberParser, uleb128, uint8ArrayParserInputCompanion));
+        return;
+    }
+    const actualUleb128 = await runParser(uleb128NumberParser, uleb128, uint8ArrayParserInputCompanion);
+    t.is(actualUleb128, natural, 'uleb128');
+}, {
+    verbose: true,
+});
+// TODO?
+testProp.skip('sleb128NumberParser on large number', [
+    fc.maxSafeInteger(),
+], async (t, integer) => {
+    const sleb128 = leb128.signed.encode(integer);
+    if (integer > (2 ** 32) - 1 || integer < -(2 ** 32)) {
+        await t.throwsAsync(() => runParser(sleb128NumberParser, sleb128, uint8ArrayParserInputCompanion));
+        return;
+    }
+    const actualSleb128 = await runParser(sleb128NumberParser, sleb128, uint8ArrayParserInputCompanion);
+    t.is(actualSleb128, integer, 'sleb128');
+}, {
+    verbose: true,
+});
+testProp('uleb128Parser on bigint', [
+    fc.bigInt({ min: 0n }),
+], async (t, bigInt) => {
+    const uleb128 = leb128.unsigned.encode(bigInt);
+    const actualUleb128 = await runParser(uleb128Parser, uleb128, uint8ArrayParserInputCompanion);
+    t.is(actualUleb128, bigInt, 'uleb128');
+}, {
+    verbose: true,
+});
+testProp('sleb128Parser on bigint', [
+    fc.bigInt(),
+], async (t, bigInt) => {
+    const sleb128 = leb128.signed.encode(bigInt);
+    const actualSleb128 = await runParser(sleb128Parser, sleb128, uint8ArrayParserInputCompanion);
+    t.is(actualSleb128, bigInt, 'sleb128');
+}, {
+    verbose: true,
+});

package/build/lookaheadParser.d.ts

@@ -0,0 +1,2 @@
+import { type Parser } from './parser.js';
+export declare const createLookaheadParser: <Output, Sequence>(childParser: Parser<Output, Sequence>) => Parser<Output, Sequence>;

package/build/lookaheadParser.js

@@ -0,0 +1,14 @@
+import { getParserName, setParserName } from './parser.js';
+export const createLookaheadParser = (childParser) => {
+    const lookaheadParser = async (parserContext) => {
+        const childParserContext = parserContext.lookahead();
+        try {
+            return await childParser(childParserContext);
+        }
+        finally {
+            childParserContext.dispose();
+        }
+    };
+    setParserName(lookaheadParser, `(?=${getParserName(childParser)})`);
+    return lookaheadParser;
+};

package/build/negativeLookaheadParser.js

@@ -1,18 +1,24 @@
-import { getParserName } from './parser.js';
+import { getParserName, setParserName } from './parser.js';
 import { ParserParsingFailedError } from './parserError.js';
-export const createNegativeLookaheadParser = (childParser) => async (parserContext) => {
-    const childParserContext = parserContext.lookahead();
-    try {
-        await childParser(childParserContext);
-        parserContext.invariant(false, 'Negative lookahead assertion failed for child parser %s.', getParserName(childParser));
-    }
-    catch (error) {
-        if (error instanceof ParserParsingFailedError) {
-            return;
+export const createNegativeLookaheadParser = (childParser) => {
+    const negativeLookaheadParser = async (parserContext) => {
+        const childParserContext = parserContext.lookahead();
+        let childParserSuccess;
+        try {
+            await childParser(childParserContext);
+            childParserSuccess = true;
         }
-        throw error;
-    }
-    finally {
-        childParserContext.dispose();
-    }
+        catch (error) {
+            if (!(error instanceof ParserParsingFailedError)) {
+                throw error;
+            }
+            childParserSuccess = false;
+        }
+        finally {
+            childParserContext.dispose();
+        }
+        parserContext.invariant(!childParserSuccess, 'Negative lookahead assertion failed for child parser %s.', getParserName(childParser));
+    };
+    setParserName(negativeLookaheadParser, `(?!${getParserName(childParser)})`);
+    return negativeLookaheadParser;
 };

package/build/negativeLookaheadParser.test.js

@@ -0,0 +1,30 @@
+import * as fc from 'fast-check';
+import { testProp } from '@fast-check/ava';
+import { createNegativeLookaheadParser } from './negativeLookaheadParser.js';
+import { createExactSequenceParser } from './exactSequenceParser.js';
+import { runParser } from './parser.js';
+import { stringParserInputCompanion } from './parserInputCompanion.js';
+import { createTupleParser } from './tupleParser.js';
+import { ParserParsingFailedError } from './parserError.js';
+testProp('negativeLookaheadParser', [
+    fc.tuple(fc.string({
+        minLength: 1,
+    }), fc.string({
+        minLength: 1,
+    })).filter(([a, b]) => !a.startsWith(b))
+], async (t, [stringA, stringB]) => {
+    const result = await runParser(createTupleParser([
+        createNegativeLookaheadParser(createExactSequenceParser(stringB)),
+        createExactSequenceParser(stringA + stringB),
+    ]), stringA + stringB, stringParserInputCompanion);
+    t.deepEqual(result, [undefined, stringA + stringB]);
+    await t.throwsAsync(() => runParser(createTupleParser([
+        createNegativeLookaheadParser(createExactSequenceParser(stringA)),
+        createExactSequenceParser(stringA + stringB),
+    ]), stringA + stringB, stringParserInputCompanion), {
+        instanceOf: ParserParsingFailedError,
+        message: /lookahead/,
+    });
+}, {
+    verbose: true,
+});

package/build/nonEmptyArrayParser.d.ts

@@ -0,0 +1,2 @@
+import { type Parser } from './parser.js';
+export declare const createNonEmptyArrayParser: <ElementOutput, Sequence>(elementParser: Parser<ElementOutput, Sequence>) => Parser<ElementOutput[], Sequence>;

package/build/nonEmptyArrayParser.js

@@ -0,0 +1,32 @@
+import { getParserName, setParserName } from './parser.js';
+import { ParserParsingFailedError } from './parserError.js';
+export const createNonEmptyArrayParser = (elementParser) => {
+    const nonEmptyArrayParser = async (parserContext) => {
+        const elements = [];
+        while (true) {
+            const elementParserContext = parserContext.lookahead();
+            const initialPosition = elementParserContext.position;
+            try {
+                const element = await elementParser(elementParserContext);
+                if (elementParserContext.position === initialPosition) {
+                    break;
+                }
+                elements.push(element);
+                elementParserContext.unlookahead();
+            }
+            catch (error) {
+                if (error instanceof ParserParsingFailedError) {
+                    break;
+                }
+                throw error;
+            }
+            finally {
+                elementParserContext.dispose();
+            }
+        }
+        parserContext.invariant(elements.length > 0, 'Expected elementParser (%s) to match at least once', getParserName(elementParser, 'anonymousNonEmptyArrayChild'));
+        return elements;
+    };
+    setParserName(nonEmptyArrayParser, getParserName(elementParser, 'anonymousNonEmptyArrayChild') + '+');
+    return nonEmptyArrayParser;
+};

package/build/nonEmptyArrayParser.test.js

@@ -0,0 +1,16 @@
+import test from 'ava';
+import { createNonEmptyArrayParser } from './nonEmptyArrayParser.js';
+import { runParser } from './parser.js';
+import { stringParserInputCompanion } from './parserInputCompanion.js';
+import { createExactElementParser } from './exactElementParser.js';
+test('empty array does not match', async (t) => {
+    const parser = createNonEmptyArrayParser(createExactElementParser('0'));
+    await t.throwsAsync(() => runParser(parser, '', stringParserInputCompanion), {
+        message: /Expected .* to match at least once/,
+    });
+});
+test('non-empty array matches', async (t) => {
+    const parser = createNonEmptyArrayParser(createExactElementParser('0'));
+    const result = await runParser(parser, '0', stringParserInputCompanion);
+    t.deepEqual(result, ['0']);
+});

package/build/parser.d.ts

@@ -1,10 +1,19 @@
+import { Class } from 'type-fest';
 import { type ParserInputCompanion } from './parserInputCompanion.js';
 import { type ParserContext } from './parserContext.js';
 import { type DeriveSequenceElement } from './sequence.js';
-export type Parser<Output, Sequence, Element = DeriveSequenceElement<Sequence>> = (parserContext: ParserContext<Sequence, Element>) => Promise<Output>;
+export type Parser<Output, Sequence, Element = DeriveSequenceElement<Sequence>> = (parserContext: ParserContext<Sequence, Element>) => Output | Promise<Output>;
 export declare function getParserName(parser: Parser<any, any, any>, default_?: string): string;
 export declare function setParserName<Output, Sequence, Element = DeriveSequenceElement<Sequence>>(parser: Parser<Output, Sequence, Element>, name: string): Parser<Output, Sequence, Element>;
+export declare function cloneParser<Output, Sequence, Element = DeriveSequenceElement<Sequence>>(parser: Parser<Output, Sequence, Element>): Parser<Output, Sequence, Element>;
 export type RunParserOptions<Output, Sequence, Element = DeriveSequenceElement<Sequence>> = {
     errorJoinMode?: 'none' | 'deepest' | 'furthest' | 'all';
+    parserContextClass?: Class<ParserContext<Sequence, Element>>;
 };
+export type RunParserWithRemainingInputResult<Output, Sequence, Element = DeriveSequenceElement<Sequence>> = {
+    output: Output;
+    position: number;
+    remainingInput: undefined | AsyncIterable<Sequence>;
+};
+export declare function runParserWithRemainingInput<Output, Sequence, Element = DeriveSequenceElement<Sequence>>(parser: Parser<Output, Sequence, Element>, input: AsyncIterator<Sequence> | AsyncIterable<Sequence> | Iterable<Sequence> | Sequence, parserInputCompanion: ParserInputCompanion<Sequence, Element>, options?: RunParserOptions<Output, Sequence, Element>): Promise<RunParserWithRemainingInputResult<Output, Sequence, Element>>;
 export declare function runParser<Output, Sequence, Element = DeriveSequenceElement<Sequence>>(parser: Parser<Output, Sequence, Element>, input: AsyncIterator<Sequence> | AsyncIterable<Sequence> | Iterable<Sequence> | Sequence, parserInputCompanion: ParserInputCompanion<Sequence, Element>, options?: RunParserOptions<Output, Sequence, Element>): Promise<Output>;

package/build/parser.js

@@ -1,6 +1,8 @@
-import invariant from 'invariant';
 import { InputReaderImplementation } from './inputReader.js';
 import { ParserContextImplementation } from './parserContext.js';
+import { ParserError, ParserUnexpectedRemainingInputError } from './parserError.js';
+import { toAsyncIterator } from './toAsyncIterator.js';
+import { inputReaderStateCompanion } from './inputReaderState.js';
 export function getParserName(parser, default_ = 'anonymous') {
     return parser.name || default_;
 }
@@ -10,44 +12,77 @@ export function setParserName(parser, name) {
     });
     return parser;
 }
-function isAsyncIterable(value) {
-    return value && typeof value[Symbol.asyncIterator] === 'function';
-}
-function isIterable(value) {
-    return value && typeof value[Symbol.iterator] === 'function';
-}
-function isIterator(value) {
-    return value && typeof value.next === 'function';
-}
-function iteratorToAsyncIterator(iterator) {
-    return {
-        next: async () => iterator.next(),
+const originalParserByClone = new WeakMap();
+export function cloneParser(parser) {
+    const originalParser = originalParserByClone.get(parser) ?? parser;
+    const clone = (parserContext) => {
+        return originalParser(parserContext);
     };
+    setParserName(clone, getParserName(parser));
+    originalParserByClone.set(clone, originalParser);
+    return clone;
 }
-function toAsyncIterator(value) {
-    if (typeof value === 'string'
-        || value instanceof Uint8Array) {
-        return (async function* () {
-            yield value;
-        })();
+async function withEnrichedParserError(parserContext, inputReader, f) {
+    try {
+        return await f();
     }
-    if (isAsyncIterable(value)) {
-        return value[Symbol.asyncIterator]();
+    catch (error) {
+        if (error instanceof ParserError) {
+            if (error.position === undefined) {
+                error.position = parserContext.position;
+            }
+            if (error.inputReaderSate === undefined) {
+                error.inputReaderSate = inputReader.toInputReaderState();
+            }
+        }
+        throw error;
     }
-    if (isIterable(value)) {
-        return iteratorToAsyncIterator(value[Symbol.iterator]());
-    }
-    if (isIterator(value)) {
-        return iteratorToAsyncIterator(value);
-    }
-    invariant(false, 'Value must be an async iterator, async iterable, iterable or iterator got %s.', value);
 }
-export async function runParser(parser, input, parserInputCompanion, options = {}) {
+function runParserInternal(parser, input, parserInputCompanion, options = {}) {
     const inputAsyncIterator = toAsyncIterator(input);
     const inputReader = new InputReaderImplementation(parserInputCompanion, inputAsyncIterator);
-    const parserContext = new ParserContextImplementation(parserInputCompanion, inputReader, undefined, {
+    const ParserContext = options.parserContextClass ?? ParserContextImplementation;
+    const parserContext = new ParserContext(parserInputCompanion, inputReader, undefined, {
         ...options,
         debugName: 'root',
     });
-    return parser(parserContext);
+    const outputPromise = (async () => {
+        try {
+            return await parser(parserContext);
+        }
+        finally {
+            await parserContext.peek(0);
+        }
+    })();
+    return {
+        outputPromise,
+        parserContext,
+        inputReader,
+    };
+}
+export async function runParserWithRemainingInput(parser, input, parserInputCompanion, options = {}) {
+    const { outputPromise, parserContext, inputReader, } = runParserInternal(parser, input, parserInputCompanion, options);
+    return await withEnrichedParserError(parserContext, inputReader, async () => {
+        const output = await outputPromise;
+        const inputReaderState = inputReader.toInputReaderState();
+        const remainingInput = (inputReaderStateCompanion.isDone(inputReaderState)
+            ? undefined
+            : inputReaderStateCompanion.toRemainingInputAsyncIterator(inputReaderState));
+        return {
+            output,
+            position: parserContext.position,
+            remainingInput,
+        };
+    });
+}
+export async function runParser(parser, input, parserInputCompanion, options = {}) {
+    const { outputPromise, parserContext, inputReader, } = runParserInternal(parser, input, parserInputCompanion, options);
+    return await withEnrichedParserError(parserContext, inputReader, async () => {
+        const output = await outputPromise;
+        const inputReaderState = inputReader.toInputReaderState();
+        if (!inputReaderStateCompanion.isDone(inputReaderState)) {
+            throw new ParserUnexpectedRemainingInputError('Unexpected remaining input', 0, parserContext.position);
+        }
+        return output;
+    });
 }