@futpib/parser 1.0.1 → 1.0.3

package/src/stringFromAsyncIterable.ts

@@ -0,0 +1,9 @@
+export async function stringFromAsyncIterable(asyncIterable: AsyncIterable<string>) {
+	let string = '';
+
+	for await (const chunk of asyncIterable) {
+		string += chunk;
+	}
+
+	return string;
+}

package/src/terminatedArrayParser.test.ts

@@ -0,0 +1,258 @@
+import test from 'ava';
+import * as fc from 'fast-check';
+import { testProp } from '@fast-check/ava';
+import { createTerminatedArrayParser, createTerminatedArrayParserNaive, createTerminatedArrayParserUnsafe } from './terminatedArrayParser.js';
+import { type Parser, runParser } from './parser.js';
+import { stringParserInputCompanion, uint8ArrayParserInputCompanion } from './parserInputCompanion.js';
+import { HighResolutionTotalTimer } from './highResolutionTimer.js';
+import { createElementParser } from './elementParser.js';
+import { createExactSequenceParser } from './exactSequenceParser.js';
+import { createTupleParser } from './tupleParser.js';
+import { createNegativeLookaheadParser } from './negativeLookaheadParser.js';
+import { promiseCompose } from './promiseCompose.js';
+import { createUnionParser } from './unionParser.js';
+import { createExactElementParser } from './exactElementParser.js';
+
+test('terminatedArrayParser of union parsers', async t => {
+	const parser: Parser<[ number[], number ], Uint8Array> = createTerminatedArrayParser(
+		createUnionParser([
+			createExactElementParser(1),
+			createExactElementParser(2),
+		]),
+		createExactElementParser(0),
+	);
+
+	const input = new Uint8Array([ 0 ]);
+
+	const result = await runParser(parser, input, uint8ArrayParserInputCompanion);
+
+	t.deepEqual(result, [ [], 0 ]);
+});
+
+testProp(
+	'terminatedArrayParser both terminator and element matching',
+	[
+		fc.string(),
+	],
+	async (t, string) => {
+		const terminatedArrayParserNaive = createTerminatedArrayParserNaive(
+			createExactSequenceParser(string),
+			createExactSequenceParser(string),
+		);
+		const terminatedArrayParser = createTerminatedArrayParser(
+			createExactSequenceParser(string),
+			createExactSequenceParser(string),
+		);
+
+		const [
+			naiveResult,
+			result,
+		] = await Promise.allSettled([
+			runParser(
+				terminatedArrayParserNaive,
+				string,
+				stringParserInputCompanion,
+			),
+			runParser(
+				terminatedArrayParser,
+				string,
+				stringParserInputCompanion,
+			),
+		]);
+
+		t.is(naiveResult.status, 'rejected');
+
+		if (
+			result.status === 'rejected'
+			&& naiveResult.status === 'rejected'
+		) {
+			result.reason.message = 'REDACTED';
+			naiveResult.reason.message = 'REDACTED';
+		}
+
+		t.deepEqual(result, naiveResult);
+	},
+	{
+		verbose: true,
+	},
+);
+
+const naiveTotalTimer = new HighResolutionTotalTimer();
+const optimizedTotalTimer = new HighResolutionTotalTimer();
+const unsafeTotalTimer = new HighResolutionTotalTimer();
+
+testProp.serial(
+	'terminatedArrayParser',
+	[
+		fc
+			.integer({
+				min: 1,
+				max: 2 ** 8,
+			})
+			.chain(terminatorLength => (
+				fc
+					.string({
+						minLength: terminatorLength,
+					})
+					.map(string => ({
+						string,
+						terminator: string.slice(0 - terminatorLength),
+					}))
+					.filter(({ string, terminator }) => string.split(terminator).length === 2)
+			)),
+	],
+	async (t, { string, terminator }) => {
+		const terminatedArrayParserNaive = createTerminatedArrayParserNaive(
+			promiseCompose(
+				createTupleParser([
+					createNegativeLookaheadParser(createExactSequenceParser(terminator)),
+					createElementParser<string>(),
+				]),
+				([ _, element ]) => element,
+			),
+			createExactSequenceParser(terminator),
+		);
+		const terminatedArrayParser = createTerminatedArrayParser(
+			promiseCompose(
+				createTupleParser([
+					createNegativeLookaheadParser(createExactSequenceParser(terminator)),
+					createElementParser<string>(),
+				]),
+				([ _, element ]) => element,
+			),
+			createExactSequenceParser(terminator),
+		);
+
+		const createTestWrapperParser = (innerParser: typeof terminatedArrayParser): Parser<{
+			string: string;
+			terminator: string;
+			position: number;
+		}, string> => async parserContext => {
+			const [ characters, terminator ] = await innerParser(parserContext);
+
+			return {
+				string: characters.join(''),
+				terminator,
+				nextPeek: await parserContext.peek(0),
+				position: parserContext.position,
+			};
+		};
+
+		const actualNaive = await naiveTotalTimer.measureAsync(async () => runParser(
+			createTestWrapperParser(terminatedArrayParserNaive),
+			string,
+			stringParserInputCompanion,
+		));
+
+		t.is(actualNaive.string.length + actualNaive.terminator.length, string.length);
+
+		const actual = await optimizedTotalTimer.measureAsync(async () => runParser(
+			createTestWrapperParser(terminatedArrayParser),
+			string,
+			stringParserInputCompanion,
+		));
+
+		t.deepEqual(actual, actualNaive);
+	},
+	{
+		verbose: true,
+	},
+);
+
+test.serial(
+	'terminatedArrayParser performance',
+	t => {
+		t.true(
+			optimizedTotalTimer.time * 1n < naiveTotalTimer.time,
+			`Naive: ${naiveTotalTimer.time / 1_000_000n}ms, Optimized: ${optimizedTotalTimer.time / 1_000_000n}ms`,
+		);
+	},
+);
+
+testProp.serial(
+	'terminatedArrayParserUnsafe',
+	[
+		fc
+			.integer({
+				min: 1,
+				max: 2 ** 8,
+			})
+			.chain(terminatorLength => (
+				fc
+					.string({
+						minLength: terminatorLength,
+					})
+					.map(string => ({
+						string,
+						terminator: string.slice(0 - terminatorLength),
+					}))
+					.filter(({ string, terminator }) => string.split(terminator).length === 2)
+			)),
+	],
+	async (t, { string, terminator }) => {
+		const terminatedArrayParserNaive = createTerminatedArrayParserNaive(
+			promiseCompose(
+				createTupleParser([
+					createNegativeLookaheadParser(createExactSequenceParser(terminator)),
+					createElementParser<string>(),
+				]),
+				([ _, element ]) => element,
+			),
+			createExactSequenceParser(terminator),
+		);
+		const terminatedArrayParserUnsafe = createTerminatedArrayParserUnsafe(
+			promiseCompose(
+				createTupleParser([
+					createNegativeLookaheadParser(createExactSequenceParser(terminator)),
+					createElementParser<string>(),
+				]),
+				([ _, element ]) => element,
+			),
+			createExactSequenceParser(terminator),
+		);
+
+		const createTestWrapperParser = (innerParser: typeof terminatedArrayParserUnsafe): Parser<{
+			string: string;
+			terminator: string;
+			position: number;
+		}, string> => async parserContext => {
+			const [ characters, terminator ] = await innerParser(parserContext);
+
+			return {
+				string: characters.join(''),
+				terminator,
+				nextPeek: await parserContext.peek(0),
+				position: parserContext.position,
+			};
+		};
+
+		const actualNaive = await runParser(
+			createTestWrapperParser(terminatedArrayParserNaive),
+			string,
+			stringParserInputCompanion,
+		);
+
+		t.is(actualNaive.string.length + actualNaive.terminator.length, string.length);
+
+		const actual = await unsafeTotalTimer.measureAsync(async () => runParser(
+			createTestWrapperParser(terminatedArrayParserUnsafe),
+			string,
+			stringParserInputCompanion,
+		));
+
+		t.deepEqual(actual, actualNaive);
+	},
+	{
+		verbose: true,
+	},
+);
+
+test.serial(
+	'terminatedArrayParserUnsafe performance',
+	t => {
+		t.true(
+			unsafeTotalTimer.time * 1n < naiveTotalTimer.time,
+			`Naive: ${naiveTotalTimer.time / 1_000_000n}ms, Unsafe: ${unsafeTotalTimer.time / 1_000_000n}ms`,
+		);
+	},
+);

package/src/terminatedArrayParser.ts

@@ -1,16 +1,16 @@
 import { getParserName, type Parser, setParserName } from './parser.js';
+import { isParserParsingFailedError, ParserParsingFailedError } from './parserError.js';
+import { parserImplementationInvariant } from './parserImplementationInvariant.js';
 import { promiseCompose } from './promiseCompose.js';
 import { createUnionParser } from './unionParser.js';
 
 class Terminated<T> {
-	constructor(
-		public readonly value: T,
-	) {}
+	constructor(public readonly value: T) {}
 }
 
-export const createTerminatedArrayParser = <ElementOutput, TerminatorOutput, Sequence>(
+export const createTerminatedArrayParserNaive = <ElementOutput, TerminatorOutput, Sequence>(
 	elementParser: Parser<ElementOutput, Sequence>,
-	terminatorParser: Parser<unknown, Sequence>,
+	terminatorParser: Parser<TerminatorOutput, Sequence>,
 ): Parser<[ElementOutput[], TerminatorOutput], Sequence> => {
 	const wrappedTerminatorParser = promiseCompose(terminatorParser, terminatorValue => new Terminated(terminatorValue));
 
@@ -24,7 +24,7 @@ export const createTerminatedArrayParser = <ElementOutput, TerminatorOutput, Seq
 		promiseCompose(terminatorParser, terminatorValue => new Terminated(terminatorValue)),
 	]);
 
-	return async parserContext => {
+	const terminatedArrayParserNaive: Parser<[ElementOutput[], TerminatorOutput], Sequence> = async parserContext => {
 		const elements: ElementOutput[] = [];
 
 		while (true) {
@@ -37,4 +37,107 @@ export const createTerminatedArrayParser = <ElementOutput, TerminatorOutput, Seq
 			elements.push(elementOrTerminator);
 		}
 	};
+
+	setParserName(terminatedArrayParserNaive, `${getParserName(elementParser, 'anonymousElement')}*?${getParserName(terminatorParser, 'anonymousTerminator')}`);
+
+	return terminatedArrayParserNaive;
+};
+
+export const createTerminatedArrayParser = <ElementOutput, TerminatorOutput, Sequence>(
+	elementParser: Parser<ElementOutput, Sequence>,
+	terminatorParser: Parser<TerminatorOutput, Sequence>,
+): Parser<[ElementOutput[], TerminatorOutput], Sequence> => {
+	const terminatedArrayParser: Parser<[ElementOutput[], TerminatorOutput], Sequence> = async parserContext => {
+		const elements: ElementOutput[] = [];
+
+		while (true) {
+			const terminatorParserContext = parserContext.lookahead({
+				debugName: getParserName(terminatorParser, 'anonymousTerminator'),
+			});
+
+			try {
+				const terminatorValue = await terminatorParser(terminatorParserContext);
+
+				const elementParserContext = parserContext.lookahead({
+					debugName: getParserName(elementParser, 'anonymousElement'),
+				});
+
+				try {
+					await elementParser(elementParserContext);
+
+					parserImplementationInvariant(
+						false,
+						[
+							'Both element and terminator parsers matched.',
+							'Element parser: %s',
+							'Terminator parser: %s',
+						],
+						getParserName(elementParser, 'anonymousElement'),
+						getParserName(terminatorParser, 'anonymousTerminator'),
+					);
+				} catch (error) {
+					if (!(isParserParsingFailedError(error))) {
+						throw error;
+					}
+				} finally {
+					elementParserContext.dispose();
+				}
+
+				terminatorParserContext.unlookahead();
+
+				return [ elements, terminatorValue ];
+			} catch (error) {
+				if (!(isParserParsingFailedError(error))) {
+					throw error;
+				}
+			} finally {
+				terminatorParserContext.dispose();
+			}
+
+			const element = await elementParser(parserContext);
+
+			elements.push(element);
+		}
+	};
+
+	setParserName(terminatedArrayParser, `${getParserName(elementParser, 'anonymousElement')}*?${getParserName(terminatorParser, 'anonymousTerminator')}`);
+
+	return terminatedArrayParser;
+};
+
+export const createTerminatedArrayParserUnsafe = <ElementOutput, TerminatorOutput, Sequence>(
+	elementParser: Parser<ElementOutput, Sequence>,
+	terminatorParser: Parser<TerminatorOutput, Sequence>,
+): Parser<[ElementOutput[], TerminatorOutput], Sequence> => {
+	const terminatedArrayParserUnsafe: Parser<[ElementOutput[], TerminatorOutput], Sequence> = async parserContext => {
+		const elements: ElementOutput[] = [];
+
+		while (true) {
+			const terminatorParserContext = parserContext.lookahead({
+				debugName: getParserName(terminatorParser, 'anonymousTerminator'),
+			});
+
+			try {
+				const terminatorValue = await terminatorParser(terminatorParserContext);
+
+				terminatorParserContext.unlookahead();
+
+				return [ elements, terminatorValue ];
+			} catch (error) {
+				if (!(isParserParsingFailedError(error))) {
+					throw error;
+				}
+			} finally {
+				terminatorParserContext.dispose();
+			}
+
+			const element = await elementParser(parserContext);
+
+			elements.push(element);
+		}
+	};
+
+	setParserName(terminatedArrayParserUnsafe, `${getParserName(elementParser, 'anonymousElement')}*?${getParserName(terminatorParser, 'anonymousTerminator')}`);
+
+	return terminatedArrayParserUnsafe;
 };

package/src/toAsyncIterable.ts

@@ -0,0 +1,7 @@
+export function toAsyncIterable<T>(value: AsyncIterator<T>): AsyncIterable<T> {
+	return {
+		[Symbol.asyncIterator]() {
+			return value;
+		},
+	};
+}

package/src/toAsyncIterator.ts

@@ -0,0 +1,48 @@
+import invariant from 'invariant';
+
+function isAsyncIterable<T>(value: unknown): value is AsyncIterable<T> {
+	return typeof value === 'object' && value !== null && Symbol.asyncIterator in value && typeof (value as Record<symbol, unknown>)[Symbol.asyncIterator] === 'function';
+}
+
+function isIterable<T>(value: unknown): value is Iterable<T> {
+	return typeof value === 'object' && value !== null && Symbol.iterator in value && typeof (value as Record<symbol, unknown>)[Symbol.iterator] === 'function';
+}
+
+function isIterator<T>(value: unknown): value is Iterator<T> {
+	return typeof value === 'object' && value !== null && 'next' in value && typeof (value as Record<string, unknown>).next === 'function';
+}
+
+function iteratorToAsyncIterator<T>(iterator: Iterator<T>): AsyncIterator<T> {
+	return {
+		next: async () => iterator.next(),
+	};
+}
+
+export function toAsyncIterator<T>(value: AsyncIterator<T> | AsyncIterable<T> | Iterable<T> | T): AsyncIterator<T> {
+	if (
+		typeof value === 'string'
+		|| value instanceof Uint8Array
+	) {
+		return (async function * () {
+			yield value as T;
+		})();
+	}
+
+	if (isAsyncIterable(value)) {
+		return value[Symbol.asyncIterator]();
+	}
+
+	if (isIterable(value)) {
+		return iteratorToAsyncIterator(value[Symbol.iterator]());
+	}
+
+	if (isIterator<T>(value)) {
+		return iteratorToAsyncIterator(value);
+	}
+
+	invariant(
+		false,
+		'Value must be an async iterator, async iterable, iterable or iterator got %s.',
+		value,
+	);
+}

package/src/tupleParser.ts

@@ -10,6 +10,10 @@ export function createTupleParser<A, B, C, D, E, F, G, H, Sequence>([ parserA, p
 export function createTupleParser<A, B, C, D, E, F, G, H, I, Sequence>([ parserA, parserB, parserC, parserD, parserE, parserF, parserG, parserH, parserI ]: [Parser<A, Sequence>, Parser<B, Sequence>, Parser<C, Sequence>, Parser<D, Sequence>, Parser<E, Sequence>, Parser<F, Sequence>, Parser<G, Sequence>, Parser<H, Sequence>, Parser<I, Sequence>]): Parser<[A, B, C, D, E, F, G, H, I], Sequence>;
 export function createTupleParser<A, B, C, D, E, F, G, H, I, J, Sequence>([ parserA, parserB, parserC, parserD, parserE, parserF, parserG, parserH, parserI, parserJ ]: [Parser<A, Sequence>, Parser<B, Sequence>, Parser<C, Sequence>, Parser<D, Sequence>, Parser<E, Sequence>, Parser<F, Sequence>, Parser<G, Sequence>, Parser<H, Sequence>, Parser<I, Sequence>, Parser<J, Sequence>]): Parser<[A, B, C, D, E, F, G, H, I, J], Sequence>;
 export function createTupleParser<A, B, C, D, E, F, G, H, I, J, K, Sequence>([ parserA, parserB, parserC, parserD, parserE, parserF, parserG, parserH, parserI, parserJ, parserK ]: [Parser<A, Sequence>, Parser<B, Sequence>, Parser<C, Sequence>, Parser<D, Sequence>, Parser<E, Sequence>, Parser<F, Sequence>, Parser<G, Sequence>, Parser<H, Sequence>, Parser<I, Sequence>, Parser<J, Sequence>, Parser<K, Sequence>]): Parser<[A, B, C, D, E, F, G, H, I, J, K], Sequence>;
+export function createTupleParser<A, B, C, D, E, F, G, H, I, J, K, L, Sequence>([ parserA, parserB, parserC, parserD, parserE, parserF, parserG, parserH, parserI, parserJ, parserK, parserL ]: [Parser<A, Sequence>, Parser<B, Sequence>, Parser<C, Sequence>, Parser<D, Sequence>, Parser<E, Sequence>, Parser<F, Sequence>, Parser<G, Sequence>, Parser<H, Sequence>, Parser<I, Sequence>, Parser<J, Sequence>, Parser<K, Sequence>, Parser<L, Sequence>]): Parser<[A, B, C, D, E, F, G, H, I, J, K, L], Sequence>;
+export function createTupleParser<A, B, C, D, E, F, G, H, I, J, K, L, M, Sequence>([ parserA, parserB, parserC, parserD, parserE, parserF, parserG, parserH, parserI, parserJ, parserK, parserL, parserM ]: [Parser<A, Sequence>, Parser<B, Sequence>, Parser<C, Sequence>, Parser<D, Sequence>, Parser<E, Sequence>, Parser<F, Sequence>, Parser<G, Sequence>, Parser<H, Sequence>, Parser<I, Sequence>, Parser<J, Sequence>, Parser<K, Sequence>, Parser<L, Sequence>, Parser<M, Sequence>]): Parser<[A, B, C, D, E, F, G, H, I, J, K, L, M], Sequence>;
+export function createTupleParser<A, B, C, D, E, F, G, H, I, J, K, L, M, N, Sequence>([ parserA, parserB, parserC, parserD, parserE, parserF, parserG, parserH, parserI, parserJ, parserK, parserL, parserM, parserN ]: [Parser<A, Sequence>, Parser<B, Sequence>, Parser<C, Sequence>, Parser<D, Sequence>, Parser<E, Sequence>, Parser<F, Sequence>, Parser<G, Sequence>, Parser<H, Sequence>, Parser<I, Sequence>, Parser<J, Sequence>, Parser<K, Sequence>, Parser<L, Sequence>, Parser<M, Sequence>, Parser<N, Sequence>]): Parser<[A, B, C, D, E, F, G, H, I, J, K, L, M, N], Sequence>;
+export function createTupleParser<A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, Sequence>([ parserA, parserB, parserC, parserD, parserE, parserF, parserG, parserH, parserI, parserJ, parserK, parserL, parserM, parserN, parserO ]: [Parser<A, Sequence>, Parser<B, Sequence>, Parser<C, Sequence>, Parser<D, Sequence>, Parser<E, Sequence>, Parser<F, Sequence>, Parser<G, Sequence>, Parser<H, Sequence>, Parser<I, Sequence>, Parser<J, Sequence>, Parser<K, Sequence>, Parser<L, Sequence>, Parser<M, Sequence>, Parser<N, Sequence>, Parser<O, Sequence>]): Parser<[A, B, C, D, E, F, G, H, I, J, K, L, M, N, O], Sequence>;
 export function createTupleParser<Sequence>(parsers: Array<Parser<unknown, Sequence>>): Parser<unknown[], Sequence> {
 	const tupleParser: Parser<unknown[], Sequence> = async parserContext => {
 		const values: unknown[] = [];
@@ -23,11 +27,10 @@ export function createTupleParser<Sequence>(parsers: Array<Parser<unknown, Seque
 		return values;
 	};
 
-	setParserName(tupleParser, [
-		'[',
-		parsers.map(parser => getParserName(parser, 'anonymousTupleChild')).join(','),
-		']',
-	].join(''));
+	setParserName(
+		tupleParser,
+		parsers.map(parser => '(' + getParserName(parser, 'anonymousTupleChild') + ')').join(''),
+	);
 
 	return tupleParser;
 }

package/src/uint8Array.ts

@@ -1,10 +1,9 @@
 
-export async function uint8ArrayAsyncIterableToUint8Array(
-	uint8ArrayAsyncIterable: AsyncIterable<Uint8Array> | Iterable<Uint8Array>,
-): Promise<Uint8Array> {
+export async function uint8ArrayAsyncIterableToUint8Array(uint8ArrayAsyncIterable: AsyncIterable<Uint8Array> | Iterable<Uint8Array>): Promise<Uint8Array> {
 	const chunks: Uint8Array[] = [];
 	for await (const chunk of uint8ArrayAsyncIterable) {
 		chunks.push(chunk);
 	}
+
 	return Buffer.concat(chunks);
 }

package/src/unionParser.test.ts

@@ -0,0 +1,78 @@
+import test from 'ava';
+import { createUnionParser } from './unionParser.js';
+import { type Parser, runParser, setParserName } from './parser.js';
+import { stringParserInputCompanion } from './parserInputCompanion.js';
+import { createArrayParser } from './arrayParser.js';
+import { createExactElementParser } from './exactElementParser.js';
+import { createExactSequenceParser } from './exactSequenceParser.js';
+import { ParserError } from './parserError.js';
+
+test('union of union of union', async t => {
+	const parser: Parser<string, string> = createUnionParser([
+		createExactElementParser('a'),
+		createUnionParser([
+			createExactElementParser('b'),
+			createUnionParser([
+				createExactElementParser('c'),
+				createExactElementParser('d'),
+			]),
+			createExactElementParser('e'),
+		]),
+		createExactElementParser('f'),
+		createUnionParser([
+			createExactElementParser('g'),
+			createExactElementParser('h'),
+		]),
+	]);
+
+	for (const character of 'abcdefgh') {
+		t.deepEqual(await runParser(parser, character, stringParserInputCompanion), character);
+	}
+});
+
+test('sync and async child parsers', async t => {
+	const parser = createArrayParser(createUnionParser<string, string>([
+		async parserContext => {
+			parserContext.invariant(
+				parserContext.position % 2 === 0,
+				'Expected an even position.',
+			);
+
+			return parserContext.read(0);
+		},
+		parserContext => {
+			parserContext.invariant(
+				parserContext.position % 2 === 1,
+				'Expected an odd position.',
+			);
+
+			parserContext.skip(1);
+
+			return String.fromCodePoint('A'.codePointAt(0)! + parserContext.position - 1);
+		},
+	]));
+
+	const result = await runParser(parser, 'a?c?', stringParserInputCompanion, {
+		errorJoinMode: 'all',
+	});
+
+	t.deepEqual(result, [ ...'aBcD' ]);
+});
+
+test('multiple parsers succeeded error', async t => {
+	const parser = createUnionParser([
+		setParserName(createExactSequenceParser('foo'), 'foo1'),
+		setParserName(createExactSequenceParser('foo'), 'foo2'),
+	]);
+
+	const error = await t.throwsAsync(runParser(parser, 'foo', stringParserInputCompanion, {
+		errorJoinMode: 'all',
+	}), {
+		any: true,
+		name: 'ParserImplementationInvariantError',
+	}) as ParserError;
+
+	t.true(error.message.includes('foo'));
+	t.true(error.message.includes('foo1'));
+	t.true(error.message.includes('foo2'));
+});