@futpib/parser 1.0.2 → 1.0.4

package/src/parser.test.ts

@@ -4,14 +4,10 @@ import { createUnionParser } from './unionParser.js';
 import { type Parser, runParser, runParserWithRemainingInput } from './parser.js';
 import { stringParserInputCompanion, uint8ArrayParserInputCompanion } from './parserInputCompanion.js';
 import {
+    isParserParsingJoinError,
+    normalParserErrorModule,
 	ParserError,
-	ParserParsingInvariantError,
-	ParserParsingJoinAllError,
-	ParserParsingJoinDeepestError,
 	ParserParsingJoinError,
-	ParserParsingJoinFurthestError,
-	ParserParsingJoinNoneError,
-	ParserUnexpectedRemainingInputError,
 } from './parserError.js';
 import { createTupleParser } from './tupleParser.js';
 import { promiseCompose } from './promiseCompose.js';
@@ -20,6 +16,7 @@ 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>([
 	createExactSequenceNaiveParser('1'),
@@ -54,74 +51,66 @@ async function * asyncIteratorFromString(string: string) {
 	yield string;
 }
 
-async function stringFromAsyncIterable(asyncIterable: AsyncIterable<string>) {
-	let string = '';
-
-	for await (const chunk of asyncIterable) {
-		string += chunk;
-	}
-
-	return 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');
 });
@@ -129,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);
 });
@@ -164,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());
 
@@ -208,9 +257,12 @@ test('thrown error has input reader state', async t => {
 				yield 'bar';
 			})(),
 			stringParserInputCompanion,
+			{
+				errorStack: true,
+			},
 		),
 		{
-			instanceOf: ParserError,
+			instanceOf: normalParserErrorModule.ParserParsingInvariantError,
 		},
 	);
 
@@ -244,10 +296,11 @@ test('thrown error has input reader state', async t => {
 
 test('runParser throws with remaining input', async t => {
 	const parser: Parser<string, string> = createExactSequenceNaiveParser('foo');
-	const error = await t.throwsAsync(() => runParser(parser, 'foobar', stringParserInputCompanion), {
-		instanceOf: ParserUnexpectedRemainingInputError,
+	const error = await t.throwsAsync(async () => runParser(parser, 'foobar', stringParserInputCompanion), {
+		any: true,
+		name: 'ParserUnexpectedRemainingInputError',
 		message: /remaining input/,
-	});
+	}) as ParserError;
 
 	t.is(error.position, 3);
 
@@ -270,7 +323,7 @@ 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.deepEqual(output, 'foo');
+	t.is(output, 'foo');
 });
 
 test('runParserWithRemainingInput with remaining input', async t => {
@@ -283,8 +336,8 @@ test('runParserWithRemainingInput with remaining input', async t => {
 	} = await runParserWithRemainingInput(parser, 'foobar', stringParserInputCompanion);
 
 	t.deepEqual(resultRest, {});
-	t.deepEqual(output, 'foo');
-	t.deepEqual(await stringFromAsyncIterable(remainingInput!), 'bar');
+	t.is(output, 'foo');
+	t.is(await stringFromAsyncIterable(remainingInput!), 'bar');
 	t.is(position, 3);
 });
 
@@ -292,6 +345,6 @@ test('runParserWithRemainingInput without remaining input', async t => {
 	const parser: Parser<string, string> = createExactSequenceNaiveParser('foo');
 	const { output, remainingInput } = await runParserWithRemainingInput(parser, 'foo', stringParserInputCompanion);
 
-	t.deepEqual(output, 'foo');
+	t.is(output, 'foo');
 	t.is(remainingInput, undefined);
 });

package/src/parser.test.ts.md

@@ -16,25 +16,25 @@ Generated by [AVA](https://avajs.dev).
 > Snapshot 1
 
     `ParserParsingJoinAllError: No union child parser succeeded.␊
-    Child error stacks, indented:␊
+    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.␊
-      Child error stacks, indented:␊
+      All child error stacks, indented:␊
         ParserParsingJoinAllError: No union child parser succeeded.␊
-        Child error stacks, indented:␊
+        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 child error stacks␊
+        End of all child error stacks␊
             at [LOCATIONS]␊
         ParserParsingInvariantError: Expected "2", got "f", at [LOCATIONS]␊
         ParserParsingInvariantError: Expected "b", got "f", at [LOCATIONS]␊
         ParserParsingInvariantError: Expected "B", got "f", at [LOCATIONS]␊
-      End of child error stacks␊
+      End of all child error stacks␊
           at [LOCATIONS]␊
       ParserParsingInvariantError: Expected "C", got "!", at [LOCATIONS]␊
-    End of child error stacks␊
+    End of all child error stacks␊
         at [LOCATIONS]`
 
 ## errorJoinMode: deepest
@@ -66,3 +66,10 @@ Generated by [AVA](https://avajs.dev).
       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.`

package/src/parser.ts

@@ -1,11 +1,14 @@
-import { Class } from 'type-fest';
+import { type Class } from 'type-fest';
 import { type ParserInputCompanion } from './parserInputCompanion.js';
 import { InputReaderImplementation } from './inputReader.js';
 import { type ParserContext, ParserContextImplementation } from './parserContext.js';
 import { type DeriveSequenceElement } from './sequence.js';
-import { ParserError, ParserUnexpectedRemainingInputError } from './parserError.js';
 import { toAsyncIterator } from './toAsyncIterator.js';
 import { inputReaderStateCompanion } from './inputReaderState.js';
+import { isLazyMessageError } from './lazyMessageError.js';
+import { isParserError, isParserParsingFailedError, normalParserErrorModule, noStackCaptureOverheadParserErrorModule, ParserError } from './parserError.js';
+import { NoStackCaptureOverheadError } from './noStackCaptureOverheadError.js';
+import invariant from 'invariant';
 
 export type Parser<
 	Output,
@@ -13,6 +16,7 @@ export type Parser<
 	Element = DeriveSequenceElement<Sequence>,
 > = (parserContext: ParserContext<Sequence, Element>) => Output | Promise<Output>;
 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function getParserName(parser: Parser<any, any, any>, default_ = 'anonymous'): string {
 	return parser.name || default_;
 }
@@ -29,20 +33,17 @@ export function setParserName<
 	return parser;
 }
 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 const originalParserByClone = new WeakMap<Parser<any, any, any>, Parser<any, any, any>>();
 
 export function cloneParser<
 	Output,
 	Sequence,
 	Element = DeriveSequenceElement<Sequence>,
->(
-	parser: Parser<Output, Sequence, Element>,
-): Parser<Output, Sequence, Element> {
+>(parser: Parser<Output, Sequence, Element>): Parser<Output, Sequence, Element> {
 	const originalParser = originalParserByClone.get(parser) ?? parser;
 
-	const clone: Parser<Output, Sequence, Element> = (parserContext) => {
-		return originalParser(parserContext);
-	};
+	const clone: Parser<Output, Sequence, Element> = parserContext => originalParser(parserContext);
 
 	setParserName(clone, getParserName(parser));
 
@@ -57,6 +58,7 @@ export type RunParserOptions<
 	Element = DeriveSequenceElement<Sequence>,
 > = {
 	errorJoinMode?: 'none' | 'deepest' | 'furthest' | 'all';
+	errorStack?: boolean;
 	parserContextClass?: Class<ParserContext<Sequence, Element>>;
 };
 
@@ -82,7 +84,27 @@ async function withEnrichedParserError<
 	try {
 		return await f();
 	} catch (error) {
-		if (error instanceof ParserError) {
+		if (error instanceof NoStackCaptureOverheadError) {
+			invariant(
+				error.name in normalParserErrorModule,
+				'NoStackCaptureOverheadError with unknown name encountered during parser execution: %s',
+				error.name,
+			);
+
+			// eslint-disable-next-line @typescript-eslint/no-explicit-any
+		const normalError: ParserError = new ((normalParserErrorModule as any)[error.name])(error.message);
+			Object.assign(normalError, error);
+
+			normalError.stack = normalError.stack + '\nIf you need a useful stack trace, pass `errorStack: true` to `runParser`, trading off some performance.';
+
+			error = normalError;
+		}
+
+		if (isLazyMessageError(error)) {
+			error.computeMessage();
+		}
+
+		if (isParserError(error)) {
 			if (error.position === undefined) {
 				error.position = parserContext.position;
 			}
@@ -124,6 +146,7 @@ function runParserInternal<
 
 	const parserContext = new ParserContext<Sequence, Element>(parserInputCompanion, inputReader, undefined, {
 		...options,
+		errorsModule: options.errorStack ? normalParserErrorModule : noStackCaptureOverheadParserErrorModule,
 		debugName: 'root',
 	});
 
@@ -158,7 +181,7 @@ export async function runParserWithRemainingInput<
 		inputReader,
 	} = runParserInternal(parser, input, parserInputCompanion, options);
 
-	return await withEnrichedParserError(parserContext, inputReader, async () => {
+	return withEnrichedParserError(parserContext, inputReader, async () => {
 		const output = await outputPromise;
 
 		const inputReaderState = inputReader.toInputReaderState();
@@ -193,13 +216,13 @@ export async function runParser<
 		inputReader,
 	} = runParserInternal(parser, input, parserInputCompanion, options);
 
-	return await withEnrichedParserError(parserContext, inputReader, async () => {
+	return 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);
+			throw new normalParserErrorModule.ParserUnexpectedRemainingInputError('Unexpected remaining input', 0, parserContext.position);
 		}
 
 		return output;

package/src/parserAccessorParser.ts

@@ -10,4 +10,4 @@ export const createParserAccessorParser = <Output, Sequence>(parserAccessor: ()
 	};
 
 	return parserAccessorParser;
-}
+};

package/src/parserConsumedSequenceParser.ts

@@ -1,5 +1,5 @@
-import { createFixedLengthSequenceParser } from "./fixedLengthSequenceParser.js";
-import { getParserName, Parser, setParserName } from "./parser.js";
+import { createFixedLengthSequenceParser } from './fixedLengthSequenceParser.js';
+import { getParserName, type Parser, setParserName } from './parser.js';
 
 export const createParserConsumedSequenceParser = <Output, Sequence>(
 	childParser: Parser<Output, Sequence>,
@@ -20,7 +20,7 @@ export const createParserConsumedSequenceParser = <Output, Sequence>(
 		const consumedSequenceParser = createFixedLengthSequenceParser<Sequence>(consumedLength);
 		const consumedSequence = await consumedSequenceParser(parserContext);
 
-		return [value, consumedSequence];
+		return [ value, consumedSequence ];
 	};
 
 	setParserName(parserConsumedSequenceParser, `parserConsumedSequenceParser(${getParserName(childParser, 'anonymousParserConsumedSequenceParserChild')})`);

package/src/parserContext.test.ts

@@ -2,13 +2,15 @@ import test from 'ava';
 import { ParserContextImplementation } from './parserContext.js';
 import { stringParserInputCompanion } from './parserInputCompanion.js';
 import { InputReaderImplementation } from './inputReader.js';
-import { ParserUnexpectedEndOfInputError } from './parserError.js';
+import { noStackCaptureOverheadParserErrorModule } from './parserError.js';
 
 const commonParserContextArguments = [
 	undefined,
 	{
 		debugName: 'root',
 		errorJoinMode: 'all',
+		errorStack: false,
+		errorsModule: noStackCaptureOverheadParserErrorModule,
 	},
 ] as const;
 
@@ -26,7 +28,8 @@ test('parserContext.read', async t => {
 	t.is(await parserContext.read(5), 'h');
 
 	await t.throwsAsync(async () => parserContext.read(0), {
-		instanceOf: ParserUnexpectedEndOfInputError,
+		any: true,
+		name: 'ParserUnexpectedEndOfInputError',
 	});
 });
 
@@ -49,7 +52,8 @@ test('parserContext.readSequence', async t => {
 	t.is(await parserContext.readSequence(0, 0), '');
 
 	await t.throwsAsync(async () => parserContext.readSequence(0, 1), {
-		instanceOf: ParserUnexpectedEndOfInputError,
+		any: true,
+		name: 'ParserUnexpectedEndOfInputError',
 	});
 });