@futpib/parser 1.0.0

package/build/optionalParser.js

@@ -0,0 +1,23 @@
+import { getParserName, setParserName } from "./parser.js";
+import { ParserParsingFailedError } from "./parserError.js";
+export const createOptionalParser = (childParser) => {
+    const optionalParser = async (parserContext) => {
+        const childParserContext = parserContext.lookahead();
+        try {
+            const value = await childParser(childParserContext);
+            childParserContext.unlookahead();
+            return value;
+        }
+        catch (error) {
+            if (error instanceof ParserParsingFailedError) {
+                return undefined;
+            }
+            throw error;
+        }
+        finally {
+            childParserContext.dispose();
+        }
+    };
+    setParserName(optionalParser, getParserName(childParser, 'anonymousOptionalChild') + '?');
+    return optionalParser;
+};

package/build/parser.d.ts

@@ -0,0 +1,10 @@
+import { type InputCompanion } from './inputCompanion.js';
+import { type ParserContext } from './parserContext.js';
+import { DeriveSequenceElement } from './sequence.js';
+export type Parser<Output, Sequence, Element = DeriveSequenceElement<Sequence>> = (parserContext: ParserContext<Sequence, Element>) => 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 type RunParserOptions<Output, Sequence, Element = DeriveSequenceElement<Sequence>> = {
+    errorJoinMode?: 'none' | 'deepest' | 'furthest' | 'all';
+};
+export declare function runParser<Output, Sequence, Element = DeriveSequenceElement<Sequence>>(parser: Parser<Output, Sequence, Element>, input: AsyncIterator<Sequence> | AsyncIterable<Sequence> | Iterable<Sequence> | Sequence, inputCompanion: InputCompanion<Sequence, Element>, options?: RunParserOptions<Output, Sequence, Element>): Promise<Output>;

package/build/parser.js

@@ -0,0 +1,53 @@
+import invariant from 'invariant';
+import { InputReaderImplementation } from './inputReader.js';
+import { ParserContextImplementation } from './parserContext.js';
+export function getParserName(parser, default_ = 'anonymous') {
+    return parser.name || default_;
+}
+export function setParserName(parser, name) {
+    Object.defineProperty(parser, 'name', {
+        value: 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(),
+    };
+}
+function toAsyncIterator(value) {
+    if (typeof value === 'string'
+        || value instanceof Uint8Array) {
+        return (async function* () {
+            yield value;
+        })();
+    }
+    if (isAsyncIterable(value)) {
+        return value[Symbol.asyncIterator]();
+    }
+    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, inputCompanion, options = {}) {
+    const inputAsyncIterator = toAsyncIterator(input);
+    const inputReader = new InputReaderImplementation(inputCompanion, inputAsyncIterator);
+    const parserContext = new ParserContextImplementation(inputCompanion, inputReader, undefined, {
+        ...options,
+        debugName: 'root',
+    });
+    return parser(parserContext);
+}

package/build/parser.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/parser.test.js

@@ -0,0 +1,126 @@
+import test from 'ava';
+import { createUnionParser } from './unionParser.js';
+import { runParser } from './parser.js';
+import { stringInputCompanion, uint8ArrayInputCompanion } from './inputCompanion.js';
+import { ParserParsingInvariantError, ParserParsingJoinAllError, ParserParsingJoinDeepestError, ParserParsingJoinError, ParserParsingJoinFurthestError, ParserParsingJoinNoneError } from './parserError.js';
+import { createTupleParser } from './tupleParser.js';
+import { promiseCompose } from './promiseCompose.js';
+import { createDisjunctionParser } from './disjunctionParser.js';
+import invariant from 'invariant';
+import { createExactSequenceParser } from './exactSequenceParser.js';
+import { createArrayParser } from './arrayParser.js';
+import { createElementParser } from './elementParser.js';
+const aUnionParser = createUnionParser([
+    createExactSequenceParser('1'),
+    createExactSequenceParser('aa'),
+    createExactSequenceParser('AAA'),
+]);
+const abDisjunctionParser = createDisjunctionParser([
+    aUnionParser,
+    createExactSequenceParser('2'),
+    createExactSequenceParser('bb'),
+    createExactSequenceParser('BBB'),
+]);
+const abcUnionParser = createUnionParser([
+    abDisjunctionParser,
+    createExactSequenceParser('final_3'),
+    createExactSequenceParser('final_cc'),
+    createExactSequenceParser('final_CCC'),
+]);
+const sampleParser = promiseCompose(createTupleParser([
+    aUnionParser,
+    abDisjunctionParser,
+    abcUnionParser,
+]), strings => strings.join(''));
+async function* asyncIteratorFromString(string) {
+    yield string;
+}
+function sortChildErrors(error) {
+    error.childErrors.sort((a, b) => a.message.localeCompare(b.message));
+    for (const childError of error.childErrors) {
+        if (childError instanceof ParserParsingJoinError) {
+            sortChildErrors(childError);
+        }
+    }
+}
+function removeStackLocations(errorStack) {
+    return errorStack.replace(/((at [^\n]+)[\s\n]+)+(at [^\n]+)/g, 'at [LOCATIONS]');
+}
+test('errorJoinMode: none', async (t) => {
+    const error = await t.throwsAsync(runParser(sampleParser, asyncIteratorFromString('1bbfinal_CC!'), stringInputCompanion, {
+        errorJoinMode: 'none',
+    }), {
+        instanceOf: ParserParsingJoinNoneError
+    });
+    t.is(error.position, 12);
+    t.deepEqual(error.childErrors, []);
+    t.snapshot(removeStackLocations(error.stack));
+});
+test('errorJoinMode: all', async (t) => {
+    const error = await t.throwsAsync(runParser(sampleParser, asyncIteratorFromString('1bbfinal_CC!'), stringInputCompanion, {
+        errorJoinMode: 'all',
+    }), {
+        instanceOf: ParserParsingJoinAllError
+    });
+    sortChildErrors(error);
+    t.snapshot(removeStackLocations(error.stack));
+    t.is(error.position, 12, 'error.position');
+    t.is(error.childErrors.length, 4);
+    const error1 = error.childErrors.at(-1);
+    invariant(error1 instanceof ParserParsingJoinAllError, 'error1 instanceof ParserParsingJoinAllError');
+    t.is(error1.position, 3, 'error1.position');
+    t.is(error1.childErrors.length, 4);
+    const error2 = error1.childErrors.at(-1);
+    invariant(error2 instanceof ParserParsingJoinAllError, 'error2 instanceof ParserParsingJoinAllError');
+    t.is(error2.position, 4, 'error2.position');
+    t.is(error2.childErrors.length, 3);
+    const error3 = error2.childErrors.at(-1);
+    invariant(error3 instanceof ParserParsingInvariantError, 'error3 instanceof ParserParsingInvariantError');
+    t.is(error3.position, 4, 'error3.position');
+});
+test('errorJoinMode: deepest', async (t) => {
+    const error = await t.throwsAsync(runParser(sampleParser, asyncIteratorFromString('1bbfinal_CC!'), stringInputCompanion, {
+        errorJoinMode: 'deepest',
+    }), {
+        instanceOf: ParserParsingJoinDeepestError,
+    });
+    sortChildErrors(error);
+    t.snapshot(removeStackLocations(error.stack));
+    t.is(error.position, 12);
+    t.is(error.childErrors.length, 1);
+    const error1 = error.childErrors.at(-1);
+    invariant(error1 instanceof ParserParsingJoinDeepestError, 'error1 instanceof ParserParsingJoinDeepestError');
+    t.is(error1.position, 3);
+    t.is(error1.childErrors.length, 1);
+    const error2 = error1.childErrors.at(-1);
+    invariant(error2 instanceof ParserParsingJoinDeepestError, 'error2 instanceof ParserParsingJoinDeepestError');
+    t.is(error2.position, 4);
+    t.is(error2.childErrors.length, 3);
+    const error3 = error2.childErrors.at(-1);
+    invariant(error3 instanceof ParserParsingInvariantError, 'error3 instanceof ParserParsingInvariantError');
+    t.is(error3.position, 4);
+});
+test('errorJoinMode: furthest', async (t) => {
+    const error = await t.throwsAsync(runParser(sampleParser, asyncIteratorFromString('1bbfinal_CC!'), stringInputCompanion, {
+        errorJoinMode: 'furthest',
+    }), {
+        instanceOf: ParserParsingJoinFurthestError,
+    });
+    sortChildErrors(error);
+    t.snapshot(removeStackLocations(error.stack));
+    t.is(error.position, 12);
+    t.is(error.childErrors.length, 1);
+    const error1 = error.childErrors.at(-1);
+    invariant(error1 instanceof ParserParsingInvariantError, 'error1 instanceof ParserParsingInvariantError');
+    t.is(error1.position, 12);
+});
+test('throws on inputCompanion type mismatch', async (t) => {
+    const anythingParser = createArrayParser(createElementParser());
+    await runParser(anythingParser, asyncIteratorFromString('anything'), stringInputCompanion);
+    await runParser(anythingParser, 'anything', stringInputCompanion);
+    await runParser(anythingParser, Buffer.from('anything'), uint8ArrayInputCompanion);
+    await runParser(anythingParser, new Uint8Array([1, 2, 3]), uint8ArrayInputCompanion);
+    await t.throwsAsync(runParser(anythingParser, asyncIteratorFromString('anything'), uint8ArrayInputCompanion), {
+        message: /input companion/,
+    });
+});

package/build/parserAccessorParser.d.ts

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

package/build/parserAccessorParser.js

@@ -0,0 +1 @@
+export const createParserAccessorParser = (parserAccessor) => async (parserContext) => parserAccessor()(parserContext);

package/build/parserCompose.d.ts

@@ -0,0 +1,3 @@
+import { Parser } from "./parser.js";
+import { DeriveSequenceElement } from "./sequence.js";
+export declare function parserCreatorCompose<OutputA, OutputB, Sequence, Element = DeriveSequenceElement<Sequence>>(f1: Parser<OutputA, Sequence, Element>, f2: (outputA: OutputA) => Parser<OutputB, Sequence, Element>): Parser<OutputB, Sequence, Element>;

package/build/parserCompose.js

@@ -0,0 +1,7 @@
+export function parserCreatorCompose(f1, f2) {
+    return async (parserContext) => {
+        const outputA = await f1(parserContext);
+        const parserB = f2(outputA);
+        return parserB(parserContext);
+    };
+}

package/build/parserContext.d.ts

@@ -0,0 +1,48 @@
+import { type InputCompanion } from './inputCompanion.js';
+import { type InputReader } from './inputReader.js';
+import { ParserParsingFailedError } from './parserError.js';
+import { RunParserOptions } from './parser.js';
+import { Falsy, ValueOrAccessor } from './parserInvariant.js';
+type LookaheadOptions = {
+    debugName?: string;
+    sliceEnd?: number;
+};
+type ParserContextOptions<Sequence, Element> = RunParserOptions<unknown, Sequence, Element> & LookaheadOptions;
+export type ParserContext<Sequence, Element> = {
+    from(elements: Element[]): Sequence;
+    length(sequence: Sequence): number;
+    at(sequence: Sequence, index: number): Element | undefined;
+    get position(): number;
+    peek(offset: number): Promise<Element | undefined>;
+    skip(offset: number): void;
+    read(offset: number): Promise<Element>;
+    lookahead(options?: LookaheadOptions): ParserContext<Sequence, Element>;
+    unlookahead(): void;
+    dispose(): void;
+    invariant<T>(value: T, format: ValueOrAccessor<string | string[]>, ...formatArguments: any[]): Exclude<T, Falsy>;
+    invariantJoin<T>(value: T, childErrors: ParserParsingFailedError[], format: ValueOrAccessor<string | string[]>, ...formatArguments: any[]): Exclude<T, Falsy>;
+};
+export declare class ParserContextImplementation<Sequence, Element> implements ParserContext<Sequence, Element> {
+    private readonly _inputCompanion;
+    private _inputReader;
+    private _parentParserContext;
+    private readonly _options;
+    private readonly _id;
+    private readonly _depth;
+    private _exclusiveChildParserContext;
+    constructor(_inputCompanion: InputCompanion<Sequence, Element>, _inputReader: InputReader<Sequence, Element>, _parentParserContext: ParserContextImplementation<Sequence, Element> | undefined, _options: ParserContextOptions<Sequence, Element>);
+    get [Symbol.toStringTag](): string;
+    from(elements: Element[]): Sequence;
+    length(sequence: Sequence): number;
+    at(sequence: Sequence, index: number): Element | undefined;
+    get position(): number;
+    peek(offset: number): Promise<Element | undefined>;
+    skip(offset: number): void;
+    read(offset: number): Promise<Element>;
+    lookahead(options?: LookaheadOptions): ParserContext<Sequence, Element>;
+    unlookahead(): void;
+    dispose(): void;
+    invariant<T>(value: T, format: ValueOrAccessor<string | string[]>, ...formatArguments: any[]): Exclude<T, Falsy>;
+    invariantJoin<T>(value: T, childErrors: ParserParsingFailedError[], format: ValueOrAccessor<string | string[]>, ...formatArguments: any[]): Exclude<T, Falsy>;
+}
+export {};

package/build/parserContext.js

@@ -0,0 +1,193 @@
+import invariant from 'invariant';
+import { ParserUnexpectedEndOfInputError, ParserParsingInvariantError, ParserParsingJoinNoneError, ParserParsingJoinAllError, ParserParsingJoinDeepestError, ParserParsingJoinFurthestError } from './parserError.js';
+import { parserInvariant } from './parserInvariant.js';
+let parserContextId = 0;
+export class ParserContextImplementation {
+    _inputCompanion;
+    _inputReader;
+    _parentParserContext;
+    _options;
+    _id = parserContextId++;
+    _depth;
+    _exclusiveChildParserContext = undefined;
+    constructor(_inputCompanion, _inputReader, _parentParserContext = undefined, _options) {
+        this._inputCompanion = _inputCompanion;
+        this._inputReader = _inputReader;
+        this._parentParserContext = _parentParserContext;
+        this._options = _options;
+        this._depth = _parentParserContext ? _parentParserContext._depth + 1 : 0;
+    }
+    get [Symbol.toStringTag]() {
+        return [
+            'ParserContext',
+            [
+                this._options.debugName,
+                '(',
+                this._id,
+                ')',
+            ].join(''),
+            this._inputReader.toString(),
+        ].join(' ');
+    }
+    from(elements) {
+        return this._inputCompanion.from(elements);
+    }
+    length(sequence) {
+        return this._inputCompanion.length(sequence);
+    }
+    at(sequence, index) {
+        return this._inputCompanion.at(sequence, index);
+    }
+    get position() {
+        return this._inputReader.position;
+    }
+    async peek(offset) {
+        if (this._options.sliceEnd !== undefined
+            && (this.position + offset) >= this._options.sliceEnd) {
+            return undefined;
+        }
+        return this._inputReader.peek(offset);
+    }
+    skip(offset) {
+        this._inputReader.skip(offset);
+    }
+    async read(offset) {
+        const element = await this.peek(offset);
+        if (element === undefined) {
+            throw new ParserUnexpectedEndOfInputError('', this._depth, this.position);
+        }
+        this.skip(offset + 1);
+        return element;
+    }
+    lookahead(options = {}) {
+        const lookaheadInputReader = this._inputReader.lookahead();
+        if (this.position !== lookaheadInputReader.position) {
+            debugger;
+        }
+        invariant(this.position === lookaheadInputReader.position, 'lookahead this.position (%s) === lookaheadInputReader.position (%s)', this.position, lookaheadInputReader.position);
+        const lookaheadParserContext = new ParserContextImplementation(this._inputCompanion, lookaheadInputReader, this, {
+            ...this._options,
+            ...options,
+            debugName: [
+                this._options.debugName,
+                '(',
+                this._id,
+                ')',
+                '/',
+                options.debugName,
+            ].join(''),
+        });
+        if (this.position !== lookaheadParserContext.position) {
+            debugger;
+        }
+        invariant(this.position === lookaheadParserContext.position, 'lookahead this.position (%s) === lookaheadParserContext.position (%s)', this.position, lookaheadParserContext.position);
+        return lookaheadParserContext;
+    }
+    unlookahead() {
+        invariant(this._parentParserContext !== undefined, 'this._parentParserContext !== undefined');
+        invariant((this._parentParserContext._exclusiveChildParserContext === undefined
+            || this._parentParserContext._exclusiveChildParserContext === this), [
+            'Parent\'s exclusive child must be undefined or this',
+            'this: %s',
+            'parent: %s',
+            'parent.exclusiveChild: %s',
+        ].join('\n'), this.toString(), this._parentParserContext.toString(), this._parentParserContext._exclusiveChildParserContext?.toString());
+        invariant(this._parentParserContext.position <= this.position, 'unlookahead this._parentParserContext.position (%s) <= this.position (%s)', this._parentParserContext.position, this.position);
+        const offset = this._inputReader.position - this._parentParserContext._inputReader.position;
+        this._parentParserContext.skip(offset);
+        invariant(this._parentParserContext.position === this.position, 'unlookahead this._parentParserContext.position (%s) === this.position (%s)', this._parentParserContext.position, this.position);
+        this._inputReader = this._parentParserContext._inputReader;
+        this._parentParserContext._exclusiveChildParserContext = this;
+        if (this._exclusiveChildParserContext) {
+            this._exclusiveChildParserContext.unlookahead();
+        }
+    }
+    dispose() {
+        invariant(this._parentParserContext !== undefined, 'this._parentParserContext !== undefined');
+        invariant((this._parentParserContext._exclusiveChildParserContext === undefined
+            || this._parentParserContext._exclusiveChildParserContext === this), [
+            'Parent\'s exclusive child must be undefined or this',
+            'this: %s',
+            'parent: %s',
+            'parent.exclusiveChild: %s',
+        ].join('\n'), this.toString(), this._parentParserContext.toString(), this._parentParserContext._exclusiveChildParserContext?.toString());
+        this._parentParserContext._exclusiveChildParserContext = undefined;
+        this._parentParserContext = undefined;
+    }
+    invariant(value, format, ...formatArguments) {
+        const parserContext = this;
+        return parserInvariant(function (message) {
+            return new ParserParsingInvariantError(message, parserContext._depth, parserContext.position);
+        }, value, format, ...formatArguments);
+    }
+    invariantJoin(value, childErrors, format, ...formatArguments) {
+        invariant(childErrors.length > 0, 'childErrors.length > 0');
+        const errorJoinMode = this._options.errorJoinMode ?? 'none';
+        const parserContext = this;
+        if (errorJoinMode === 'none') {
+            return parserInvariant(function (message) {
+                return new ParserParsingJoinNoneError(message, parserContext._depth, parserContext.position);
+            }, value, format, ...formatArguments);
+        }
+        if (errorJoinMode === 'furthest') {
+            return parserInvariant(function (message) {
+                let furthestPosition = 0;
+                let furthestChildErrors = [];
+                for (const childError of childErrors) {
+                    if (childError.position < furthestPosition) {
+                        continue;
+                    }
+                    if (childError.position > furthestPosition) {
+                        furthestPosition = childError.position;
+                        furthestChildErrors = [childError];
+                        continue;
+                    }
+                    furthestChildErrors.push(childError);
+                }
+                message += [
+                    '',
+                    'Furthest child error stacks, indented:',
+                    ...furthestChildErrors.flatMap(furthestChildError => furthestChildError.stack?.split('\n').map(line => '  ' + line)),
+                    'End of furthest child error stacks',
+                ].join('\n');
+                return new ParserParsingJoinFurthestError(message, parserContext._depth, furthestPosition, furthestChildErrors);
+            }, value, format, ...formatArguments);
+        }
+        if (errorJoinMode === 'deepest') {
+            return parserInvariant(function (message) {
+                let deepestDepth = 0;
+                let deepestChildErrors = [];
+                for (const childError of childErrors) {
+                    if (childError.depth < deepestDepth) {
+                        continue;
+                    }
+                    if (childError.depth > deepestDepth) {
+                        deepestDepth = childError.depth;
+                        deepestChildErrors = [childError];
+                        continue;
+                    }
+                    deepestChildErrors.push(childError);
+                }
+                message += [
+                    '',
+                    'Deepest child error stacks, indented:',
+                    ...deepestChildErrors.flatMap(deepestChildError => deepestChildError.stack?.split('\n').map(line => '  ' + line)),
+                    'End of deepest child error stacks',
+                ].join('\n');
+                return new ParserParsingJoinDeepestError(message, deepestDepth, parserContext.position, deepestChildErrors);
+            }, value, format, ...formatArguments);
+        }
+        if (errorJoinMode === 'all') {
+            return parserInvariant(function (message) {
+                message += [
+                    '',
+                    'Child error stacks, indented:',
+                    ...childErrors.flatMap(childError => childError.stack?.split('\n').map(line => '  ' + line)),
+                    'End of child error stacks',
+                ].join('\n');
+                return new ParserParsingJoinAllError(message, parserContext._depth, parserContext.position, childErrors);
+            }, value, format, ...formatArguments);
+        }
+        invariant(false, 'Unsupported errorJoinMode: %s', errorJoinMode);
+    }
+}

package/build/parserContext.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/parserContext.test.js

@@ -0,0 +1,115 @@
+import test from 'ava';
+import { ParserContextImplementation } from './parserContext.js';
+import { stringInputCompanion } from './inputCompanion.js';
+import { InputReaderImplementation } from './inputReader.js';
+import { ParserUnexpectedEndOfInputError } from './parserError.js';
+const commonParserContextArguments = [
+    undefined,
+    {
+        debugName: 'root',
+        errorJoinMode: 'all',
+    },
+];
+test('parserContext.read', async (t) => {
+    const parserContext = new ParserContextImplementation(stringInputCompanion, new InputReaderImplementation(stringInputCompanion, (async function* () {
+        yield '';
+        yield 'abc';
+        yield 'def';
+        yield '';
+        yield 'gh';
+    })()), ...commonParserContextArguments);
+    t.is(await parserContext.read(0), 'a');
+    t.is(await parserContext.read(0), 'b');
+    t.is(await parserContext.read(5), 'h');
+    await t.throwsAsync(async () => parserContext.read(0), {
+        instanceOf: ParserUnexpectedEndOfInputError,
+    });
+});
+test('parserContext.lookahead', async (t) => {
+    const parserContext = new ParserContextImplementation(stringInputCompanion, new InputReaderImplementation(stringInputCompanion, (async function* () {
+        yield* 'abcdefgh';
+    })()), ...commonParserContextArguments);
+    const lookaheadContext1 = parserContext.lookahead();
+    const lookaheadContext2 = parserContext.lookahead();
+    const lookaheadContext3 = parserContext.lookahead({
+        sliceEnd: 3,
+    });
+    t.is(await lookaheadContext3.peek(2), 'c');
+    t.is(await lookaheadContext3.peek(3), undefined);
+    t.is(await lookaheadContext3.read(0), 'a');
+    t.is(await lookaheadContext3.read(0), 'b');
+    t.is(await lookaheadContext3.read(0), 'c');
+    t.is(await lookaheadContext3.peek(0), undefined);
+    t.is(await parserContext.peek(0), 'a');
+    t.is(await lookaheadContext1.peek(0), 'a');
+    t.is(await lookaheadContext2.peek(0), 'a');
+    t.is(await lookaheadContext1.read(0), 'a');
+    t.is(await parserContext.peek(0), 'a');
+    t.is(await lookaheadContext1.peek(0), 'b');
+    t.is(await lookaheadContext2.peek(0), 'a');
+    t.is(await parserContext.read(0), 'a');
+    t.is(parserContext.position, 1);
+    t.is(lookaheadContext1.position, 1);
+    t.is(lookaheadContext2.position, 0);
+    t.is(lookaheadContext3.position, 3);
+});
+test('parserContext.unlookahead', async (t) => {
+    const parserContext = new ParserContextImplementation(stringInputCompanion, new InputReaderImplementation(stringInputCompanion, (async function* () {
+        yield* 'abcdefgh';
+    })()), ...commonParserContextArguments);
+    const lookaheadContext = parserContext.lookahead();
+    t.is(await parserContext.peek(0), 'a');
+    t.is(await lookaheadContext.peek(0), 'a');
+    t.is(await lookaheadContext.read(0), 'a');
+    t.is(await parserContext.peek(0), 'a');
+    t.is(await lookaheadContext.peek(0), 'b');
+    lookaheadContext.unlookahead();
+    t.is(await lookaheadContext.read(0), 'b');
+    t.is(await lookaheadContext.read(0), 'c');
+});
+test('parserContext.unlookahead while peeking', async (t) => {
+    const parserContext = new ParserContextImplementation(stringInputCompanion, new InputReaderImplementation(stringInputCompanion, (async function* () {
+        yield* 'abcdefgh';
+    })()), ...commonParserContextArguments);
+    const lookaheadContext = parserContext.lookahead();
+    parserContext.skip(1);
+    lookaheadContext.skip(2);
+    const peekPromise = lookaheadContext.peek(0);
+    lookaheadContext.unlookahead();
+    t.is(await peekPromise, 'c');
+});
+test('parserContext deep unlookahead normal order', async (t) => {
+    const parserContext = new ParserContextImplementation(stringInputCompanion, new InputReaderImplementation(stringInputCompanion, (async function* () {
+        yield* 'abcdefgh';
+    })()), ...commonParserContextArguments);
+    const child = parserContext.lookahead();
+    t.is(await child.read(0), 'a');
+    const grandchild = child.lookahead();
+    t.is(await grandchild.read(0), 'b');
+    grandchild.unlookahead();
+    t.is(await child.read(0), 'c');
+    child.unlookahead();
+    t.is(await parserContext.read(0), 'd');
+});
+test('parserContext deep unlookahead weird order', async (t) => {
+    const parserContext = new ParserContextImplementation(stringInputCompanion, new InputReaderImplementation(stringInputCompanion, (async function* () {
+        yield* 'abcdefgh';
+    })()), ...commonParserContextArguments);
+    const child = parserContext.lookahead({
+        debugName: 'child',
+    });
+    const grandchild = child.lookahead({
+        debugName: 'grandchild',
+    });
+    const greatGrandchild = grandchild.lookahead({
+        debugName: 'greatGrandchild',
+    });
+    t.is(await greatGrandchild.read(0), 'a');
+    grandchild.unlookahead();
+    child.unlookahead();
+    greatGrandchild.unlookahead();
+    t.is(await greatGrandchild.read(0), 'b');
+    t.is(await grandchild.read(0), 'c');
+    t.is(await child.read(0), 'd');
+    t.is(await parserContext.read(0), 'e');
+});

package/build/parserCreatorCompose.d.ts

@@ -0,0 +1,3 @@
+import { Parser } from "./parser.js";
+import { DeriveSequenceElement } from "./sequence.js";
+export declare function parserCreatorCompose<Arguments extends unknown[], OutputA, OutputB, Sequence, Element = DeriveSequenceElement<Sequence>>(f1: (...args: Arguments) => Parser<OutputA, Sequence, Element>, f2: (outputA: OutputA) => Parser<OutputB, Sequence, Element>): (...args: Arguments) => Parser<OutputB, Sequence, Element>;

package/build/parserCreatorCompose.js

@@ -0,0 +1,10 @@
+export function parserCreatorCompose(f1, f2) {
+    return (...args) => {
+        const parserA = f1(...args);
+        return async (parserContext) => {
+            const outputA = await parserA(parserContext);
+            const parserB = f2(outputA);
+            return parserB(parserContext);
+        };
+    };
+}

package/build/parserError.d.ts

@@ -0,0 +1,43 @@
+export declare class ParserError extends Error {
+    name: string;
+}
+export declare class ParserImplementationError extends ParserError {
+    name: string;
+}
+export declare class ParserImplementationInvariantError extends ParserImplementationError {
+    name: string;
+}
+export declare class ParserParsingFailedError extends ParserError {
+    readonly depth: number;
+    readonly position: number;
+    name: string;
+    constructor(message: string, depth: number, position: number);
+}
+export declare class ParserParsingJoinError extends ParserParsingFailedError {
+    name: string;
+    readonly childErrors: ParserParsingFailedError[];
+}
+export declare class ParserParsingJoinNoneError extends ParserParsingJoinError {
+    name: string;
+}
+export declare class ParserParsingJoinAllError extends ParserParsingJoinError {
+    readonly childErrors: ParserParsingFailedError[];
+    name: string;
+    constructor(message: string, depth: number, position: number, childErrors: ParserParsingFailedError[]);
+}
+export declare class ParserParsingJoinDeepestError extends ParserParsingJoinError {
+    readonly childErrors: ParserParsingFailedError[];
+    name: string;
+    constructor(message: string, depth: number, position: number, childErrors: ParserParsingFailedError[]);
+}
+export declare class ParserParsingJoinFurthestError extends ParserParsingJoinError {
+    readonly childErrors: ParserParsingFailedError[];
+    name: string;
+    constructor(message: string, depth: number, position: number, childErrors: ParserParsingFailedError[]);
+}
+export declare class ParserParsingInvariantError extends ParserParsingFailedError {
+    name: string;
+}
+export declare class ParserUnexpectedEndOfInputError extends ParserParsingFailedError {
+    name: string;
+}