@futpib/parser 1.0.1 → 1.0.3

package/src/noStackCaptureOverheadError.ts

@@ -0,0 +1,12 @@
+
+class NoStackCaptureOverheadErrorClass extends Error {}
+
+function NoStackCaptureOverheadErrorConstructor(this: Error, message: string) {
+	this.name = 'NoStackCaptureOverheadError';
+	this.message = message;
+	this.stack = 'This stack is intentionally left blank to avoid capture overhead.';
+}
+
+NoStackCaptureOverheadErrorConstructor.prototype = Object.create(Error.prototype);
+
+export const NoStackCaptureOverheadError = NoStackCaptureOverheadErrorConstructor as unknown as typeof NoStackCaptureOverheadErrorClass

package/src/nonEmptyArrayParser.test.ts

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

package/src/nonEmptyArrayParser.ts

@@ -0,0 +1,44 @@
+import { getParserName, type Parser, setParserName } from './parser.js';
+import { isParserParsingFailedError, ParserParsingFailedError } from './parserError.js';
+
+export const createNonEmptyArrayParser = <ElementOutput, Sequence>(
+	elementParser: Parser<ElementOutput, Sequence>,
+): Parser<ElementOutput[], Sequence> => {
+	const nonEmptyArrayParser: Parser<ElementOutput[], Sequence> = async parserContext => {
+		const elements: ElementOutput[] = [];
+
+		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 (isParserParsingFailedError(error)) {
+					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/src/optionalParser.ts

@@ -1,17 +1,18 @@
 import { getParserName, type Parser, setParserName } from './parser.js';
-import { ParserParsingFailedError } from './parserError.js';
+import { isParserParsingFailedError, ParserParsingFailedError } from './parserError.js';
 
 export const createOptionalParser = <Output, Sequence>(
 	childParser: Parser<Output, Sequence>,
 ): Parser<undefined | Output, Sequence> => {
 	const optionalParser: Parser<undefined | Output, Sequence> = async parserContext => {
 		const childParserContext = parserContext.lookahead();
+
 		try {
 			const value = await childParser(childParserContext);
 			childParserContext.unlookahead();
 			return value;
 		} catch (error) {
-			if (error instanceof ParserParsingFailedError) {
+			if (isParserParsingFailedError(error)) {
 				return undefined;
 			}
 

package/src/parser.test.ts

@@ -1,36 +1,41 @@
 import test from 'ava';
 import invariant from 'invariant';
 import { createUnionParser } from './unionParser.js';
-import { type Parser, runParser } from './parser.js';
+import { type Parser, runParser, runParserWithRemainingInput } from './parser.js';
 import { stringParserInputCompanion, uint8ArrayParserInputCompanion } from './parserInputCompanion.js';
 import {
-	ParserParsingInvariantError, ParserParsingJoinAllError, ParserParsingJoinDeepestError, ParserParsingJoinError, ParserParsingJoinFurthestError, ParserParsingJoinNoneError,
+    isParserParsingJoinError,
+    normalParserErrorModule,
+	ParserError,
+	ParserParsingJoinError,
 } from './parserError.js';
 import { createTupleParser } from './tupleParser.js';
 import { promiseCompose } from './promiseCompose.js';
 import { createDisjunctionParser } from './disjunctionParser.js';
-import { createExactSequenceParser } from './exactSequenceParser.js';
+import { createExactSequenceNaiveParser } from './exactSequenceParser.js';
 import { createArrayParser } from './arrayParser.js';
 import { createElementParser } from './elementParser.js';
+import { toAsyncIterable } from './toAsyncIterable.js';
+import { stringFromAsyncIterable } from './stringFromAsyncIterable.js';
 
 const aUnionParser = createUnionParser<string, string>([
-	createExactSequenceParser('1'),
-	createExactSequenceParser('aa'),
-	createExactSequenceParser('AAA'),
+	createExactSequenceNaiveParser('1'),
+	createExactSequenceNaiveParser('aa'),
+	createExactSequenceNaiveParser('AAA'),
 ]);
 
 const abDisjunctionParser = createDisjunctionParser<string, string>([
 	aUnionParser,
-	createExactSequenceParser('2'),
-	createExactSequenceParser('bb'),
-	createExactSequenceParser('BBB'),
+	createExactSequenceNaiveParser('2'),
+	createExactSequenceNaiveParser('bb'),
+	createExactSequenceNaiveParser('BBB'),
 ]);
 
 const abcUnionParser = createUnionParser<string, string>([
 	abDisjunctionParser,
-	createExactSequenceParser('final_3'),
-	createExactSequenceParser('final_cc'),
-	createExactSequenceParser('final_CCC'),
+	createExactSequenceNaiveParser('final_3'),
+	createExactSequenceNaiveParser('final_cc'),
+	createExactSequenceNaiveParser('final_CCC'),
 ]);
 
 const sampleParser = promiseCompose(
@@ -46,64 +51,66 @@ async function * asyncIteratorFromString(string: string) {
 	yield string;
 }
 
-function sortChildErrors(error: ParserParsingJoinNoneError) {
+function sortChildErrors(error: ParserParsingJoinError) {
 	error.childErrors.sort((a, b) => a.message.localeCompare(b.message));
 
 	for (const childError of error.childErrors) {
-		if (childError instanceof ParserParsingJoinError) {
+		if (isParserParsingJoinError(childError)) {
 			sortChildErrors(childError);
 		}
 	}
 }
 
-function removeStackLocations(errorStack: string) {
-	return errorStack.replaceAll(/((at [^\n]+)[\s\n]+)+(at [^\n]+)/g, 'at [LOCATIONS]');
+function removeStackLocations(errorStack: string | undefined) {
+	return errorStack?.replaceAll(/((at [^\n]+)[\s\n]+)+(at [^\n]+)/g, 'at [LOCATIONS]');
 }
 
 test('errorJoinMode: none', async t => {
 	const error = await t.throwsAsync(runParser(sampleParser, asyncIteratorFromString('1bbfinal_CC!'), stringParserInputCompanion, {
 		errorJoinMode: 'none',
+		errorStack: true,
 	}), {
-		instanceOf: ParserParsingJoinNoneError,
+		instanceOf: normalParserErrorModule.ParserParsingJoinNoneError,
 	});
 
 	t.is(error.position, 12);
 	t.deepEqual(error.childErrors, []);
 
-	t.snapshot(removeStackLocations(error.stack!));
+	t.snapshot(removeStackLocations(error.stack));
 });
 
 test('errorJoinMode: all', async t => {
 	const error = await t.throwsAsync(runParser(sampleParser, asyncIteratorFromString('1bbfinal_CC!'), stringParserInputCompanion, {
 		errorJoinMode: 'all',
+		errorStack: true,
 	}), {
-		instanceOf: ParserParsingJoinAllError,
+		instanceOf: normalParserErrorModule.ParserParsingJoinAllError,
 	});
 
 	sortChildErrors(error);
 
-	t.snapshot(removeStackLocations(error.stack!));
+	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');
+	invariant(isParserParsingJoinError(error1), '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');
+	invariant(isParserParsingJoinError(error2), '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');
+	invariant(error3.name === 'ParserParsingInvariantError', 'error3 instanceof ParserParsingInvariantError');
 
 	t.is(error3.position, 4, 'error3.position');
 });
@@ -111,34 +118,35 @@ test('errorJoinMode: all', async t => {
 test('errorJoinMode: deepest', async t => {
 	const error = await t.throwsAsync(runParser(sampleParser, asyncIteratorFromString('1bbfinal_CC!'), stringParserInputCompanion, {
 		errorJoinMode: 'deepest',
+		errorStack: true,
 	}), {
-		instanceOf: ParserParsingJoinDeepestError,
+		instanceOf: normalParserErrorModule.ParserParsingJoinDeepestError,
 	});
 
 	sortChildErrors(error);
 
-	t.snapshot(removeStackLocations(error.stack!));
+	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');
+	invariant(isParserParsingJoinError(error1), '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');
+	invariant(isParserParsingJoinError(error2), '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');
+	invariant(error3.name === 'ParserParsingInvariantError', 'error3 instanceof ParserParsingInvariantError');
 
 	t.is(error3.position, 4);
 });
@@ -146,24 +154,83 @@ test('errorJoinMode: deepest', async t => {
 test('errorJoinMode: furthest', async t => {
 	const error = await t.throwsAsync(runParser(sampleParser, asyncIteratorFromString('1bbfinal_CC!'), stringParserInputCompanion, {
 		errorJoinMode: 'furthest',
+		errorStack: true,
 	}), {
-		instanceOf: ParserParsingJoinFurthestError,
+		instanceOf: normalParserErrorModule.ParserParsingJoinFurthestError,
 	});
 
 	sortChildErrors(error);
 
-	t.snapshot(removeStackLocations(error.stack!));
+	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');
+	invariant(error1.name === 'ParserParsingInvariantError', 'error1 instanceof ParserParsingInvariantError');
 
 	t.is(error1.position, 12);
 });
 
+test('errorStack: false', async t => {
+	const error = await t.throwsAsync(runParser(sampleParser, 'nothing like what sampleParser expects', stringParserInputCompanion, {
+		errorJoinMode: 'all',
+	}), {
+		instanceOf: normalParserErrorModule.ParserParsingJoinAllError,
+	});
+
+	t.regex(error.stack!, /intentionally left blank/);
+	t.regex(error.stack!, /errorStack: true/);
+});
+
+test('errorStack: true', async t => {
+	const error = await t.throwsAsync(runParser(sampleParser, 'nothing like what sampleParser expects', stringParserInputCompanion, {
+		errorJoinMode: 'all',
+		errorStack: true,
+	}), {
+		instanceOf: normalParserErrorModule.ParserParsingJoinAllError,
+	});
+
+	t.regex(error.stack!, /exactSequenceParser/);
+});
+
+test('errorJoinMode: none, errorStack: false', async t => {
+	const error = await t.throwsAsync(runParser(sampleParser, asyncIteratorFromString('1bbfinal_CC!'), stringParserInputCompanion, {
+		errorJoinMode: 'none',
+		errorStack: false,
+	}), {
+		instanceOf: normalParserErrorModule.ParserParsingJoinNoneError,
+	});
+
+	t.is(error.position, 12);
+	t.deepEqual(error.childErrors, []);
+
+	t.snapshot(removeStackLocations(error.stack));
+});
+
+test('retrows normal errors untouched', async t => {
+	class CustomError extends Error {};
+	const originalCustomError1 = new CustomError('This is a custom error');
+	const originalCustomError2 = new Error('This is a normal error');
+
+	const error1 = await t.throwsAsync(runParser(() => {
+		throw originalCustomError1;
+	}, 'foo', stringParserInputCompanion), {
+		instanceOf: CustomError,
+	});
+
+	t.is(error1, originalCustomError1);
+
+	const error2 = await t.throwsAsync(runParser(() => {
+		throw originalCustomError2;
+	}, 'foo', stringParserInputCompanion), {
+		instanceOf: Error,
+	});
+
+	t.is(error2, originalCustomError2);
+});
+
 test('throws on parserInputCompanion type mismatch', async t => {
 	const anythingParser: Parser<any, any> = createArrayParser(createElementParser());
 
@@ -176,3 +243,108 @@ test('throws on parserInputCompanion type mismatch', async t => {
 		message: /input companion/,
 	});
 });
+
+test('thrown error has input reader state', async t => {
+	const error = await t.throwsAsync(
+		runParser(
+			createTupleParser([
+				createExactSequenceNaiveParser('foo'),
+				createExactSequenceNaiveParser('bar'),
+			]),
+			(async function * () {
+				yield 'foo';
+				yield 'qux';
+				yield 'bar';
+			})(),
+			stringParserInputCompanion,
+			{
+				errorStack: true,
+			},
+		),
+		{
+			instanceOf: normalParserErrorModule.ParserParsingInvariantError,
+		},
+	);
+
+	t.is(error.position, 4);
+
+	invariant(error.inputReaderSate, 'error.inputReaderSate');
+
+	const {
+		consumedBufferedSequences,
+		unconsumedBufferedSequences,
+		unbufferedSequences,
+		position,
+		...inputReaderStateRest
+	} = error.inputReaderSate;
+
+	t.is(position, 4);
+	t.deepEqual(inputReaderStateRest, {});
+
+	const unbufferedSequencesArray = [];
+
+	if (unbufferedSequences) {
+		for await (const sequence of toAsyncIterable(unbufferedSequences)) {
+			unbufferedSequencesArray.push(sequence);
+		}
+	}
+
+	t.deepEqual(consumedBufferedSequences, [ 'q' ]);
+	t.deepEqual(unconsumedBufferedSequences, [ 'ux' ]);
+	t.deepEqual(unbufferedSequencesArray, [ 'bar' ]);
+});
+
+test('runParser throws with remaining input', async t => {
+	const parser: Parser<string, string> = createExactSequenceNaiveParser('foo');
+	const error = await t.throwsAsync(async () => runParser(parser, 'foobar', stringParserInputCompanion), {
+		any: true,
+		name: 'ParserUnexpectedRemainingInputError',
+		message: /remaining input/,
+	}) as ParserError;
+
+	t.is(error.position, 3);
+
+	const {
+		position,
+		consumedBufferedSequences,
+		unconsumedBufferedSequences,
+		unbufferedSequences,
+		...inputReaderStateRest
+	} = error.inputReaderSate!;
+
+	t.deepEqual(inputReaderStateRest, {});
+	t.is(position, 3);
+	t.deepEqual(consumedBufferedSequences, [ 'foo' ]);
+	t.deepEqual(unconsumedBufferedSequences, [ 'bar' ]);
+	t.truthy(unbufferedSequences);
+});
+
+test('runParser does not throw without remaining input', async t => {
+	const parser: Parser<string, string> = createExactSequenceNaiveParser('foo');
+	const output = await runParser(parser, 'foo', stringParserInputCompanion);
+
+	t.is(output, 'foo');
+});
+
+test('runParserWithRemainingInput with remaining input', async t => {
+	const parser: Parser<string, string> = createExactSequenceNaiveParser('foo');
+	const {
+		output,
+		remainingInput,
+		position,
+		...resultRest
+	} = await runParserWithRemainingInput(parser, 'foobar', stringParserInputCompanion);
+
+	t.deepEqual(resultRest, {});
+	t.is(output, 'foo');
+	t.is(await stringFromAsyncIterable(remainingInput!), 'bar');
+	t.is(position, 3);
+});
+
+test('runParserWithRemainingInput without remaining input', async t => {
+	const parser: Parser<string, string> = createExactSequenceNaiveParser('foo');
+	const { output, remainingInput } = await runParserWithRemainingInput(parser, 'foo', stringParserInputCompanion);
+
+	t.is(output, 'foo');
+	t.is(remainingInput, undefined);
+});

package/src/parser.test.ts.md

@@ -8,48 +8,48 @@ Generated by [AVA](https://avajs.dev).
 
 > Snapshot 1
 
-    `ParserParsingJoinNoneError: (position: 12) No union child parser succeeded.␊
+    `ParserParsingJoinNoneError: No union child parser succeeded.␊
         at [LOCATIONS]`
 
 ## errorJoinMode: all
 
 > Snapshot 1
 
-    `ParserParsingJoinAllError: (position: 12) No union child parser succeeded.␊
-    Child error stacks, indented:␊
-      ParserParsingInvariantError: (position: 10) Expected "3", got "C", at [LOCATIONS]␊
-      ParserParsingInvariantError: (position: 10) Expected "c", got "C", at [LOCATIONS]␊
-      ParserParsingJoinAllError: (position: 3) No disjunction child parser succeeded.␊
-      Child error stacks, indented:␊
-        ParserParsingJoinAllError: (position: 4) No union child parser succeeded.␊
-        Child error stacks, indented:␊
-          ParserParsingInvariantError: (position: 4) Expected "1", got "f", at [LOCATIONS]␊
-          ParserParsingInvariantError: (position: 4) Expected "a", got "f", at [LOCATIONS]␊
-          ParserParsingInvariantError: (position: 4) Expected "A", got "f", at [LOCATIONS]␊
-        End of child error stacks␊
+    `ParserParsingJoinAllError: No union child parser succeeded.␊
+    All child error stacks, indented:␊
+      ParserParsingInvariantError: Expected "3", got "C", at [LOCATIONS]␊
+      ParserParsingInvariantError: Expected "c", got "C", at [LOCATIONS]␊
+      ParserParsingJoinAllError: No disjunction child parser succeeded.␊
+      All child error stacks, indented:␊
+        ParserParsingJoinAllError: No union child parser succeeded.␊
+        All child error stacks, indented:␊
+          ParserParsingInvariantError: Expected "1", got "f", at [LOCATIONS]␊
+          ParserParsingInvariantError: Expected "a", got "f", at [LOCATIONS]␊
+          ParserParsingInvariantError: Expected "A", got "f", at [LOCATIONS]␊
+        End of all child error stacks␊
             at [LOCATIONS]␊
-        ParserParsingInvariantError: (position: 4) Expected "2", got "f", at [LOCATIONS]␊
-        ParserParsingInvariantError: (position: 4) Expected "b", got "f", at [LOCATIONS]␊
-        ParserParsingInvariantError: (position: 4) Expected "B", got "f", at [LOCATIONS]␊
-      End of child error stacks␊
+        ParserParsingInvariantError: Expected "2", got "f", at [LOCATIONS]␊
+        ParserParsingInvariantError: Expected "b", got "f", at [LOCATIONS]␊
+        ParserParsingInvariantError: Expected "B", got "f", at [LOCATIONS]␊
+      End of all child error stacks␊
           at [LOCATIONS]␊
-      ParserParsingInvariantError: (position: 12) Expected "C", got "!", at [LOCATIONS]␊
-    End of child error stacks␊
+      ParserParsingInvariantError: Expected "C", got "!", at [LOCATIONS]␊
+    End of all child error stacks␊
         at [LOCATIONS]`
 
 ## errorJoinMode: deepest
 
 > Snapshot 1
 
-    `ParserParsingJoinDeepestError: (position: 12) No union child parser succeeded.␊
+    `ParserParsingJoinDeepestError: No union child parser succeeded.␊
     Deepest child error stacks, indented:␊
-      ParserParsingJoinDeepestError: (position: 3) No disjunction child parser succeeded.␊
+      ParserParsingJoinDeepestError: No disjunction child parser succeeded.␊
       Deepest child error stacks, indented:␊
-        ParserParsingJoinDeepestError: (position: 4) No union child parser succeeded.␊
+        ParserParsingJoinDeepestError: No union child parser succeeded.␊
         Deepest child error stacks, indented:␊
-          ParserParsingInvariantError: (position: 4) Expected "1", got "f", at [LOCATIONS]␊
-          ParserParsingInvariantError: (position: 4) Expected "a", got "f", at [LOCATIONS]␊
-          ParserParsingInvariantError: (position: 4) Expected "A", got "f", at [LOCATIONS]␊
+          ParserParsingInvariantError: Expected "1", got "f", at [LOCATIONS]␊
+          ParserParsingInvariantError: Expected "a", got "f", at [LOCATIONS]␊
+          ParserParsingInvariantError: Expected "A", got "f", at [LOCATIONS]␊
         End of deepest child error stacks␊
             at [LOCATIONS]␊
       End of deepest child error stacks␊
@@ -61,8 +61,15 @@ Generated by [AVA](https://avajs.dev).
 
 > Snapshot 1
 
-    `ParserParsingJoinFurthestError: (position: 12) No union child parser succeeded.␊
+    `ParserParsingJoinFurthestError: No union child parser succeeded.␊
     Furthest child error stacks, indented:␊
-      ParserParsingInvariantError: (position: 12) Expected "C", got "!", at [LOCATIONS]␊
+      ParserParsingInvariantError: Expected "C", got "!", at [LOCATIONS]␊
     End of furthest child error stacks␊
         at [LOCATIONS]`
+
+## errorJoinMode: none, errorStack: false
+
+> Snapshot 1
+
+    `This stack is intentionally left blank to avoid capture overhead.␊
+    If you need a useful stack trace, pass \`errorStack: true\` to \`runParser\`, trading off some performance.`