@futpib/parser 1.0.4 → 1.0.6

package/src/negativeLookaheadParser.ts

@@ -5,7 +5,7 @@ export const createNegativeLookaheadParser = <Sequence>(
 	childParser: Parser<unknown, Sequence>,
 ): Parser<void, Sequence> => {
 	const negativeLookaheadParser: Parser<void, Sequence> = async parserContext => {
-		const childParserContext = parserContext.lookahead();
+		using childParserContext = parserContext.lookahead();
 
 		let childParserSuccess: boolean;
 
@@ -19,8 +19,6 @@ export const createNegativeLookaheadParser = <Sequence>(
 			}
 
 			childParserSuccess = false;
-		} finally {
-			childParserContext.dispose();
 		}
 
 		parserContext.invariant(

package/src/nonEmptyArrayParser.ts

@@ -8,7 +8,7 @@ export const createNonEmptyArrayParser = <ElementOutput, Sequence>(
 		const elements: ElementOutput[] = [];
 
 		while (true) {
-			const elementParserContext = parserContext.lookahead();
+			using elementParserContext = parserContext.lookahead();
 			const initialPosition = elementParserContext.position;
 			try {
 				const element = await elementParser(elementParserContext);
@@ -24,8 +24,6 @@ export const createNonEmptyArrayParser = <ElementOutput, Sequence>(
 				}
 
 				throw error;
-			} finally {
-				elementParserContext.dispose();
 			}
 		}
 

package/src/objectParser.test-d.ts

@@ -0,0 +1,152 @@
+import { expectAssignable, expectNotAssignable, expectType } from 'tsd';
+import { createObjectParser } from './objectParser.js';
+import { type Parser, type ParserOutput } from './parser.js';
+import { createExactSequenceParser } from './exactSequenceParser.js';
+import { createFixedLengthSequenceParser } from './fixedLengthSequenceParser.js';
+
+// Test: parsers only - extracts output types
+{
+	const parser = createObjectParser({
+		first: createFixedLengthSequenceParser<string>(3),
+		second: createFixedLengthSequenceParser<string>(3),
+	});
+
+	type Output = ParserOutput<typeof parser>;
+
+	// Output should be assignable to and from expected type
+	expectAssignable<{ first: string; second: string }>(null! as Output);
+	expectAssignable<Output>(null! as { first: string; second: string });
+}
+
+// Test: literal types are preserved
+{
+	const parser = createObjectParser({
+		type: 'block' as const,
+		name: createFixedLengthSequenceParser<string>(3),
+	});
+
+	type Output = ParserOutput<typeof parser>;
+
+	// 'block' literal should be preserved
+	expectAssignable<{ type: 'block'; name: string }>(null! as Output);
+	expectType<'block'>(null! as Output['type']);
+}
+
+// Test: underscore keys excluded from result type
+{
+	const parser = createObjectParser({
+		first: createFixedLengthSequenceParser<string>(3),
+		_sep: createExactSequenceParser(':'),
+		second: createFixedLengthSequenceParser<string>(3),
+	});
+
+	type Output = ParserOutput<typeof parser>;
+
+	// Should have first and second but not _sep
+	expectAssignable<{ first: string; second: string }>(null! as Output);
+
+	// _sep should NOT be a key in Output
+	expectNotAssignable<{ _sep: string }>(null! as Output);
+}
+
+// Test: mixed literals and parsers with underscore keys
+{
+	const parser = createObjectParser({
+		type: 'assignment' as const,
+		_open: createExactSequenceParser('('),
+		name: createFixedLengthSequenceParser<string>(1),
+		_eq: createExactSequenceParser('='),
+		value: createFixedLengthSequenceParser<string>(1),
+		_close: createExactSequenceParser(')'),
+	});
+
+	type Output = ParserOutput<typeof parser>;
+
+	expectAssignable<{ type: 'assignment'; name: string; value: string }>(null! as Output);
+	expectType<'assignment'>(null! as Output['type']);
+
+	// Underscore keys should not exist
+	expectNotAssignable<{ _open: string }>(null! as Output);
+	expectNotAssignable<{ _eq: string }>(null! as Output);
+	expectNotAssignable<{ _close: string }>(null! as Output);
+}
+
+// Test: number literal
+{
+	const parser = createObjectParser({
+		code: 42 as const,
+		data: createFixedLengthSequenceParser<string>(2),
+	});
+
+	type Output = ParserOutput<typeof parser>;
+
+	expectAssignable<{ code: 42; data: string }>(null! as Output);
+	expectType<42>(null! as Output['code']);
+}
+
+// Test: all underscore keys results in empty object
+{
+	const parser = createObjectParser({
+		_a: createExactSequenceParser('a'),
+		_b: createExactSequenceParser('b'),
+	});
+
+	type Output = ParserOutput<typeof parser>;
+
+	// Should be assignable to empty object
+	// eslint-disable-next-line @typescript-eslint/ban-types
+	expectAssignable<{}>(null! as Output);
+
+	// Should NOT have _a or _b
+	expectNotAssignable<{ _a: string }>(null! as Output);
+	expectNotAssignable<{ _b: string }>(null! as Output);
+}
+
+// Test: boolean literal
+{
+	const parser = createObjectParser({
+		enabled: true as const,
+		name: createFixedLengthSequenceParser<string>(3),
+	});
+
+	type Output = ParserOutput<typeof parser>;
+
+	expectAssignable<{ enabled: true; name: string }>(null! as Output);
+	expectType<true>(null! as Output['enabled']);
+}
+
+// Test: null literal
+{
+	const parser = createObjectParser({
+		value: null,
+		name: createFixedLengthSequenceParser<string>(3),
+	});
+
+	type Output = ParserOutput<typeof parser>;
+
+	expectAssignable<{ value: null; name: string }>(null! as Output);
+	expectType<null>(null! as Output['value']);
+}
+
+// Test: underscore-prefixed parsers still contribute to sequence type inference
+{
+	const parser = createObjectParser({
+		_prefix: createExactSequenceParser<Uint8Array>(Buffer.from([0x00])),
+		operation: 'nop' as const,
+	});
+
+	// Parser should be assignable to Parser<{ operation: 'nop' }, Uint8Array>
+	expectAssignable<Parser<{ operation: 'nop' }, Uint8Array>>(parser);
+}
+
+// Test: sequence type inferred from underscore parser when no other parsers present
+{
+	const parser = createObjectParser({
+		_marker: createExactSequenceParser<string>('test'),
+		type: 'marker' as const,
+		value: 42 as const,
+	});
+
+	// Should infer string sequence from _marker parser
+	expectAssignable<Parser<{ type: 'marker'; value: 42 }, string>>(parser);
+}

package/src/objectParser.test.ts

@@ -0,0 +1,71 @@
+import test from 'ava';
+import { createObjectParser } from './objectParser.js';
+import { runParser } from './parser.js';
+import { stringParserInputCompanion } from './parserInputCompanion.js';
+import { createExactSequenceParser } from './exactSequenceParser.js';
+import { createFixedLengthSequenceParser } from './fixedLengthSequenceParser.js';
+
+// Type tests are in objectParser.test-d.ts (using tsd)
+
+test('parses object with parsers only', async t => {
+	const parser = createObjectParser({
+		first: createFixedLengthSequenceParser<string>(3),
+		second: createFixedLengthSequenceParser<string>(3),
+	});
+
+	const output = await runParser(parser, 'foobar', stringParserInputCompanion);
+
+	t.deepEqual(output, { first: 'foo', second: 'bar' });
+});
+
+test('parses object with literals', async t => {
+	const parser = createObjectParser({
+		type: 'block' as const,
+		value: createFixedLengthSequenceParser<string>(3),
+	});
+
+	const output = await runParser(parser, 'foo', stringParserInputCompanion);
+
+	t.deepEqual(output, { type: 'block', value: 'foo' });
+});
+
+test('excludes underscore-prefixed keys from result but runs parsers', async t => {
+	const parser = createObjectParser({
+		first: createFixedLengthSequenceParser<string>(3),
+		_separator: createExactSequenceParser(':'),
+		second: createFixedLengthSequenceParser<string>(3),
+	});
+
+	const output = await runParser(parser, 'foo:bar', stringParserInputCompanion);
+
+	t.deepEqual(output, { first: 'foo', second: 'bar' });
+	t.false('_separator' in output);
+});
+
+test('preserves property order', async t => {
+	const parser = createObjectParser({
+		c: createFixedLengthSequenceParser<string>(1),
+		a: createFixedLengthSequenceParser<string>(1),
+		b: createFixedLengthSequenceParser<string>(1),
+	});
+
+	const output = await runParser(parser, 'xyz', stringParserInputCompanion);
+
+	t.deepEqual(Object.keys(output), ['c', 'a', 'b']);
+	t.deepEqual(output, { c: 'x', a: 'y', b: 'z' });
+});
+
+test('mixed parsers and literals with underscore keys', async t => {
+	const parser = createObjectParser({
+		type: 'assignment' as const,
+		_open: createExactSequenceParser('('),
+		name: createFixedLengthSequenceParser<string>(1),
+		_eq: createExactSequenceParser('='),
+		value: createFixedLengthSequenceParser<string>(1),
+		_close: createExactSequenceParser(')'),
+	});
+
+	const output = await runParser(parser, '(x=5)', stringParserInputCompanion);
+
+	t.deepEqual(output, { type: 'assignment', name: 'x', value: '5' });
+});

package/src/objectParser.ts

@@ -0,0 +1,69 @@
+import { getParserName, setParserName, type Parser, type ParserOutput, type ParserSequence } from './parser.js';
+
+// Extract only parser values from an object (filter out literals)
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type ExtractParsers<T> = T[keyof T] & Parser<any, any, any>;
+
+// Extract Sequence from an object of parsers (finds parser's sequence type, ignoring literals)
+type InferSequenceFromParsers<T> = ParserSequence<ExtractParsers<T>>;
+
+// Extract output type: Parser<O, S> → O, literal L → L
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type ExtractOutputOrLiteral<P> = P extends Parser<any, any, any> ? ParserOutput<P> : P;
+
+// Filter out underscore-prefixed keys
+type OmitUnderscoreKeys<T> = {
+	[K in keyof T as K extends `_${string}` ? never : K]: T[K]
+};
+
+// Result type for object parser
+type ObjectParserOutput<Parsers extends Record<string, unknown>> = OmitUnderscoreKeys<{
+	[K in keyof Parsers]: ExtractOutputOrLiteral<Parsers[K]>
+}>;
+
+export function createObjectParser<
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	const Parsers extends Record<string, Parser<any, any, any> | unknown>,
+>(
+	parsers: Parsers,
+): Parser<ObjectParserOutput<Parsers>, InferSequenceFromParsers<Parsers>> {
+	type Sequence = InferSequenceFromParsers<Parsers>;
+
+	const objectParser: Parser<ObjectParserOutput<Parsers>, Sequence> = async parserContext => {
+		const result: Record<string, unknown> = {};
+
+		for (const [key, parserOrLiteral] of Object.entries(parsers)) {
+			let value: unknown;
+
+			if (typeof parserOrLiteral === 'function') {
+				// It's a parser - execute it
+				// eslint-disable-next-line @typescript-eslint/no-explicit-any
+				value = await (parserOrLiteral as Parser<unknown, any>)(parserContext);
+			} else {
+				// It's a literal - use directly
+				value = parserOrLiteral;
+			}
+
+			if (!key.startsWith('_')) {
+				result[key] = value;
+			}
+		}
+
+		return result as ObjectParserOutput<Parsers>;
+	};
+
+	setParserName(
+		objectParser,
+		'{' + Object.keys(parsers).map(k => {
+			const v = parsers[k];
+			if (typeof v === 'function') {
+				// eslint-disable-next-line @typescript-eslint/no-explicit-any
+				return k.startsWith('_') ? k : getParserName(v as Parser<unknown, any>, k);
+			}
+
+			return `${k}: ${JSON.stringify(v)}`;
+		}).join(', ') + '}',
+	);
+
+	return objectParser;
+}

package/src/optionalParser.ts

@@ -5,7 +5,7 @@ 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();
+		using childParserContext = parserContext.lookahead();
 
 		try {
 			const value = await childParser(childParserContext);
@@ -17,8 +17,6 @@ export const createOptionalParser = <Output, Sequence>(
 			}
 
 			throw error;
-		} finally {
-			childParserContext.dispose();
 		}
 	};
 

package/src/parser.test.ts

@@ -7,6 +7,7 @@ import {
     isParserParsingJoinError,
     normalParserErrorModule,
 	ParserError,
+	ParserParsingFailedError,
 	ParserParsingJoinError,
 } from './parserError.js';
 import { createTupleParser } from './tupleParser.js';
@@ -17,21 +18,23 @@ import { createArrayParser } from './arrayParser.js';
 import { createElementParser } from './elementParser.js';
 import { toAsyncIterable } from './toAsyncIterable.js';
 import { stringFromAsyncIterable } from './stringFromAsyncIterable.js';
+import { createLookaheadParser } from './lookaheadParser.js';
+import { createNegativeLookaheadParser } from './negativeLookaheadParser.js';
 
-const aUnionParser = createUnionParser<string, string>([
+const aUnionParser = createUnionParser([
 	createExactSequenceNaiveParser('1'),
 	createExactSequenceNaiveParser('aa'),
 	createExactSequenceNaiveParser('AAA'),
 ]);
 
-const abDisjunctionParser = createDisjunctionParser<string, string>([
+const abDisjunctionParser = createDisjunctionParser([
 	aUnionParser,
 	createExactSequenceNaiveParser('2'),
 	createExactSequenceNaiveParser('bb'),
 	createExactSequenceNaiveParser('BBB'),
 ]);
 
-const abcUnionParser = createUnionParser<string, string>([
+const abcUnionParser = createUnionParser([
 	abDisjunctionParser,
 	createExactSequenceNaiveParser('final_3'),
 	createExactSequenceNaiveParser('final_cc'),
@@ -39,7 +42,7 @@ const abcUnionParser = createUnionParser<string, string>([
 ]);
 
 const sampleParser = promiseCompose(
-	createTupleParser<string, string, string, string>([
+	createTupleParser([
 		aUnionParser,
 		abDisjunctionParser,
 		abcUnionParser,
@@ -332,6 +335,8 @@ test('runParserWithRemainingInput with remaining input', async t => {
 		output,
 		remainingInput,
 		position,
+		furthestReadPosition,
+		furthestPeekedPosition,
 		...resultRest
 	} = await runParserWithRemainingInput(parser, 'foobar', stringParserInputCompanion);
 
@@ -339,6 +344,8 @@ test('runParserWithRemainingInput with remaining input', async t => {
 	t.is(output, 'foo');
 	t.is(await stringFromAsyncIterable(remainingInput!), 'bar');
 	t.is(position, 3);
+	t.is(furthestReadPosition, 3);
+	t.is(furthestPeekedPosition, 3);
 });
 
 test('runParserWithRemainingInput without remaining input', async t => {
@@ -348,3 +355,143 @@ test('runParserWithRemainingInput without remaining input', async t => {
 	t.is(output, 'foo');
 	t.is(remainingInput, undefined);
 });
+
+test('furthestReadPosition equals position when no backtracking', async t => {
+	const parser: Parser<string, string> = createExactSequenceNaiveParser('foo');
+	const result = await runParserWithRemainingInput(parser, 'foobar', stringParserInputCompanion);
+
+	t.is(result.position, 3);
+	t.is(result.furthestReadPosition, 3);
+	t.is(result.furthestPeekedPosition, 3);
+});
+
+test('furthestReadPosition tracks lookahead that succeeded', async t => {
+	// Parser: lookahead('foo') followed by 'foobar'
+	// The lookahead parses 'foo' (position 3) but doesn't consume it
+	// Then 'foobar' is parsed (position 6)
+	const parser = createTupleParser([
+		createLookaheadParser(createExactSequenceNaiveParser('foo')),
+		createExactSequenceNaiveParser('foobar'),
+	]);
+
+	const result = await runParserWithRemainingInput(parser, 'foobar', stringParserInputCompanion);
+
+	t.is(result.position, 6);
+	t.is(result.furthestReadPosition, 6);
+	t.is(result.furthestPeekedPosition, 6);
+});
+
+test('furthestReadPosition tracks failed lookahead with backtracking', async t => {
+	// Parser: try 'foobar' OR 'foo'
+	// First tries 'foobar', reads 'f','o','o','q' (position 4) then fails because 'q' != 'b'
+	// Backtracks and tries 'foo', succeeds at position 3
+	// furthestReadPosition should be 4 (from the failed 'foobar' attempt that read up to 'q')
+	const parser = createDisjunctionParser([
+		createExactSequenceNaiveParser('foobar'),
+		createExactSequenceNaiveParser('foo'),
+	]);
+
+	const result = await runParserWithRemainingInput(parser, 'fooqux', stringParserInputCompanion);
+
+	t.is(result.output, 'foo');
+	t.is(result.position, 3);
+	t.is(result.furthestReadPosition, 4);
+	t.is(result.furthestPeekedPosition, 3);
+});
+
+test('furthestReadPosition exceeds position after backtracking from longer match', async t => {
+	// Parser: try 'foobarqux' OR 'foo'
+	// First tries 'foobarqux', reads up to position 6 ('foobar'), then fails
+	// Backtracks and tries 'foo', succeeds at position 3
+	// furthestReadPosition should be 6 (from the failed 'foobarqux' attempt)
+	const parser = createDisjunctionParser([
+		createExactSequenceNaiveParser('foobarqux'),
+		createExactSequenceNaiveParser('foo'),
+	]);
+
+	const result = await runParserWithRemainingInput(parser, 'foobar', stringParserInputCompanion);
+
+	t.is(result.output, 'foo');
+	t.is(result.position, 3);
+	t.is(result.furthestReadPosition, 6);
+	t.is(result.furthestPeekedPosition, 6);
+});
+
+test('furthestPeekedPosition differs from furthestReadPosition with lookahead', async t => {
+	// Parser: lookahead('foobar') then 'foo'
+	// The lookahead parses 'foobar':
+	// - Each read() calls peek(0) at positions 0,1,2,3,4,5 then skip(1) advancing to 1,2,3,4,5,6
+	// - This updates furthestReadPosition to 6 and furthestPeekedPosition to 5
+	// Then 'foo' is parsed from position 0, position becomes 3
+	// furthestReadPosition=6 (from lookahead's skip calls)
+	// furthestPeekedPosition=5 (from lookahead's peek calls at positions 0-5)
+	const parser = createTupleParser([
+		createLookaheadParser(createExactSequenceNaiveParser('foobar')),
+		createExactSequenceNaiveParser('foo'),
+	]);
+
+	const result = await runParserWithRemainingInput(parser, 'foobar', stringParserInputCompanion);
+
+	t.is(result.output[1], 'foo');
+	t.is(result.position, 3);
+	t.is(result.furthestReadPosition, 6);
+	t.is(result.furthestPeekedPosition, 5);
+});
+
+test('error has furthestReadPosition after backtracking', async t => {
+	// Parser: try 'foobarqux' OR 'foobaz'
+	// Input: 'foobar'
+	// First tries 'foobarqux', reads up to position 6 ('foobar'), then fails (no 'qux')
+	// Then tries 'foobaz', reads up to position 4 ('foob'), then fails ('b' != 'z')
+	// Both fail, error at position 0, but furthestReadPosition should be 6
+	const parser = createDisjunctionParser([
+		createExactSequenceNaiveParser('foobarqux'),
+		createExactSequenceNaiveParser('foobaz'),
+	]);
+
+	const error = await t.throwsAsync(
+		runParser(parser, 'foobar', stringParserInputCompanion, { errorStack: true }),
+	) as ParserParsingFailedError;
+
+	t.is(error.position, 0);
+	t.is(error.furthestReadPosition, 6);
+	t.is(error.furthestPeekedPosition, 6);
+});
+
+test('error from negative lookahead has furthestReadPosition from lookahead content', async t => {
+	// Parser: negativeLookahead('foobar') then 'foo'
+	// Input: 'foobar'
+	// Negative lookahead tries 'foobar', succeeds (reads to position 6)
+	// Since lookahead succeeded, negative lookahead fails
+	// Error position is 0 (where negative lookahead started), but furthestReadPosition is 6
+	const parser = createTupleParser([
+		createNegativeLookaheadParser(createExactSequenceNaiveParser('foobar')),
+		createExactSequenceNaiveParser('foo'),
+	]);
+
+	const error = await t.throwsAsync(
+		runParser(parser, 'foobar', stringParserInputCompanion, { errorStack: true }),
+		{
+			name: 'ParserParsingInvariantError',
+		},
+	) as ParserParsingFailedError;
+
+	t.is(error.position, 0);
+	t.is(error.furthestReadPosition, 6);
+	t.is(error.furthestPeekedPosition, 5);
+});
+
+test('furthestReadPosition on ParserUnexpectedRemainingInputError', async t => {
+	const parser: Parser<string, string> = createExactSequenceNaiveParser('foo');
+
+	const error = await t.throwsAsync(
+		runParser(parser, 'foobar', stringParserInputCompanion),
+		{
+			name: 'ParserUnexpectedRemainingInputError',
+		},
+	) as ParserParsingFailedError;
+
+	t.is(error.position, 3);
+	t.is(error.furthestReadPosition, 3);
+	t.is(error.furthestPeekedPosition, 3);
+});

package/src/parser.ts

@@ -16,6 +16,12 @@ export type Parser<
 	Element = DeriveSequenceElement<Sequence>,
 > = (parserContext: ParserContext<Sequence, Element>) => Output | Promise<Output>;
 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ParserOutput<P> = P extends Parser<infer O, any, any> ? O : never;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ParserSequence<P> = P extends Parser<any, infer S, any> ? S : never;
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function getParserName(parser: Parser<any, any, any>, default_ = 'anonymous'): string {
 	return parser.name || default_;
@@ -69,6 +75,8 @@ export type RunParserWithRemainingInputResult<
 > = {
 	output: Output;
 	position: number;
+	furthestReadPosition: number;
+	furthestPeekedPosition: number;
 	remainingInput: undefined | AsyncIterable<Sequence>;
 };
 
@@ -195,6 +203,8 @@ export async function runParserWithRemainingInput<
 		return {
 			output,
 			position: parserContext.position,
+			furthestReadPosition: inputReader.furthestReadPosition,
+			furthestPeekedPosition: inputReader.furthestPeekedPosition,
 			remainingInput,
 		};
 	});
@@ -222,7 +232,7 @@ export async function runParser<
 		const inputReaderState = inputReader.toInputReaderState();
 
 		if (!inputReaderStateCompanion.isDone(inputReaderState)) {
-			throw new normalParserErrorModule.ParserUnexpectedRemainingInputError('Unexpected remaining input', 0, parserContext.position);
+			throw new normalParserErrorModule.ParserUnexpectedRemainingInputError('Unexpected remaining input', 0, parserContext.position, inputReader.furthestReadPosition, inputReader.furthestPeekedPosition);
 		}
 
 		return output;

package/src/parserConsumedSequenceParser.ts

@@ -6,15 +6,13 @@ export const createParserConsumedSequenceParser = <Output, Sequence>(
 ): Parser<[Output, Sequence], Sequence> => {
 	const parserConsumedSequenceParser: Parser<[Output, Sequence], Sequence> = async parserContext => {
 		const initialPosition = parserContext.position;
-		const childParserContext = parserContext.lookahead();
 
 		let value: Output;
 		let consumedLength: number;
-		try {
+		{
+			using childParserContext = parserContext.lookahead();
 			value = await childParser(childParserContext);
 			consumedLength = childParserContext.position - initialPosition;
-		} finally {
-			childParserContext.dispose();
 		}
 
 		const consumedSequenceParser = createFixedLengthSequenceParser<Sequence>(consumedLength);