@futpib/parser 1.0.0

package/src/index.ts

@@ -0,0 +1,76 @@
+
+export {
+	Parser,
+	runParser,
+
+	setParserName,
+	getParserName,
+} from './parser.js';
+
+export {
+	ParserContext,
+} from './parserContext.js';
+
+export {
+	createTupleParser,
+} from './tupleParser.js';
+
+export {
+	createExactSequenceParser,
+} from './exactSequenceParser.js';
+
+export {
+	createFixedLengthSequenceParser,
+} from './fixedLengthSequenceParser.js';
+
+export {
+	createArrayParser,
+} from './arrayParser.js';
+
+export {
+	createOptionalParser,
+} from './optionalParser.js';
+
+export {
+	createUnionParser,
+} from './unionParser.js';
+
+export {
+	createDisjunctionParser,
+} from './disjunctionParser.js';
+
+export {
+	createParserAccessorParser,
+} from './parserAccessorParser.js';
+
+export {
+	createElementParser,
+} from './elementParser.js';
+
+export {
+	createTerminatedArrayParser,
+} from './terminatedArrayParser.js';
+
+export {
+	createSliceBoundedParser,
+} from './sliceBoundedParser.js';
+
+export {
+	createExactElementParser,
+} from './exactElementParser.js';
+
+export {
+	createSkipParser,
+} from './skipParser.js';
+
+export {
+	createEndOfInputParser,
+} from './endOfInputParser.js';
+
+export {
+	createListParser,
+} from './listParser.js';
+
+export {
+	createDebugLogParser,
+} from './debugLogParser.js';

package/src/inputCompanion.ts

@@ -0,0 +1,43 @@
+
+export type InputCompanion<Sequence, Element> = {
+	is(value: unknown): value is Sequence;
+	from(elements: Element[]): Sequence;
+	length(sequence: Sequence): number;
+	at(sequence: Sequence, index: number): Element | undefined;
+};
+
+export const stringInputCompanion = new class StringInputCompanion implements InputCompanion<string, string> {
+	is(value: unknown): value is string {
+		return typeof value === 'string';
+	}
+
+	from(elements: string[]): string {
+		return elements.join('');
+	}
+
+	length(sequence: string): number {
+		return sequence.length;
+	}
+
+	at(sequence: string, index: number): string | undefined {
+		return sequence.at(index);
+	}
+}();
+
+export const uint8ArrayInputCompanion = new class Uint8ArrayInputCompanion implements InputCompanion<Uint8Array, number> {
+	is(value: unknown): value is Uint8Array {
+		return value instanceof Uint8Array
+	}
+
+	from(elements: number[]): Uint8Array {
+		return new Uint8Array(elements);
+	}
+
+	length(sequence: Uint8Array): number {
+		return sequence.length;
+	}
+
+	at(sequence: Uint8Array, index: number): number | undefined {
+		return sequence.at(index);
+	}
+}();

package/src/inputReader.test.ts

@@ -0,0 +1,238 @@
+import test from 'ava';
+import { InputReaderImplementation } from './inputReader.js';
+import { stringInputCompanion } from './inputCompanion.js';
+import { ParserImplementationError } from './parserError.js';
+
+test('inputReader', async t => {
+	const inputReader = new InputReaderImplementation(stringInputCompanion, (async function * () {
+		yield '';
+		yield 'abc';
+		yield 'def';
+		yield '';
+		yield 'gh';
+	})());
+
+	t.is(await inputReader.peek(0), 'a');
+
+	inputReader.skip(0);
+
+	t.is(await inputReader.peek(1), 'b');
+
+	inputReader.skip(1);
+
+	t.is(await inputReader.peek(1), 'c');
+	t.is(await inputReader.peek(2), 'd');
+	t.is(await inputReader.peek(3), 'e');
+	t.is(await inputReader.peek(4), 'f');
+	t.is(await inputReader.peek(5), 'g');
+	t.is(await inputReader.peek(6), 'h');
+	t.is(await inputReader.peek(7), undefined);
+
+	inputReader.skip(6);
+
+	t.is(await inputReader.peek(0), 'h');
+	t.is(await inputReader.peek(1), undefined);
+
+	inputReader.skip(1);
+
+	t.is(await inputReader.peek(0), undefined);
+
+	inputReader.skip(0);
+
+	t.is(await inputReader.peek(0), undefined);
+
+	inputReader.skip(1);
+
+	t.is(await inputReader.peek(0), undefined);
+});
+
+test('inputReader.peek concurrent', async t => {
+	const inputReader = new InputReaderImplementation(stringInputCompanion, (async function * () {
+		yield * 'abcdefgh';
+	})());
+
+	const peeks = await Promise.all([
+		inputReader.peek(0),
+		inputReader.peek(0),
+		inputReader.peek(0),
+		inputReader.peek(0),
+		inputReader.peek(1),
+		inputReader.peek(2),
+		inputReader.peek(3),
+		inputReader.peek(4),
+		inputReader.peek(5),
+		inputReader.peek(6),
+		inputReader.peek(7),
+	]);
+
+	t.deepEqual(peeks, [ 'a', 'a', 'a', 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h' ]);
+});
+
+test('inputReader skip while peeking', async t => {
+	const inputReader = new InputReaderImplementation(stringInputCompanion, (async function * () {
+		yield * 'abcdefgh';
+	})());
+
+	const peekPromise = inputReader.peek(0);
+
+	inputReader.skip(1);
+
+	t.is(await peekPromise, 'a');
+	t.is(await inputReader.peek(0), 'b');
+});
+
+test('inputReader.lookahead', async t => {
+	let read = 0;
+
+	const inputReader = new InputReaderImplementation(stringInputCompanion, (async function * () {
+		for (const character of 'abcdefgh') {
+			read++;
+			yield character;
+		}
+	})());
+
+	const lookahead0a = inputReader.lookahead();
+	const lookahead0b = lookahead0a.lookahead();
+	const lookahead0c = lookahead0b.lookahead();
+
+	t.is(await inputReader.peek(0), 'a');
+	t.is(await lookahead0a.peek(0), 'a');
+	t.is(await lookahead0b.peek(0), 'a');
+	t.is(await lookahead0c.peek(0), 'a');
+
+	t.is(inputReader.position, 0);
+	t.is(lookahead0a.position, 0);
+	t.is(lookahead0b.position, 0);
+	t.is(lookahead0c.position, 0);
+
+	t.is(read, 1);
+
+	t.is(await lookahead0b.peek(1), 'b');
+	t.is(await inputReader.peek(0), 'a');
+
+	t.is(read, 2);
+
+	inputReader.skip(1);
+
+	await t.throwsAsync(async () => lookahead0a.peek(0), {
+		instanceOf: ParserImplementationError,
+	});
+	await t.throwsAsync(async () => lookahead0b.peek(0));
+	await t.throwsAsync(async () => lookahead0c.peek(0));
+
+	const lookahead1a = inputReader.lookahead();
+	const lookahead1b = inputReader.lookahead();
+
+	t.is(await lookahead1a.peek(0), 'b');
+	t.is(await lookahead1b.peek(0), 'b');
+
+	t.is(lookahead1a.position, 1);
+	t.is(lookahead1b.position, 1);
+
+	lookahead1a.skip(1);
+
+	t.is(await lookahead1a.peek(0), 'c');
+	t.is(await lookahead1b.peek(0), 'b');
+
+	t.is(lookahead1a.position, 2);
+	t.is(lookahead1b.position, 1);
+
+	const lookahead2a = lookahead1a.lookahead();
+	const lookahead2b = lookahead1a.lookahead();
+
+	lookahead2a.skip(1);
+
+	t.is(await lookahead2a.peek(0), 'd');
+	t.is(await lookahead2b.peek(0), 'c');
+
+	t.is(lookahead2a.position, 3);
+	t.is(lookahead2b.position, 2);
+
+	t.is(read, 4);
+
+	t.is(await inputReader.peek(0), 'b');
+
+	t.is(inputReader.position, 1);
+
+	inputReader.skip(1);
+
+	t.is(await inputReader.peek(0), 'c');
+
+	t.is(inputReader.position, 2);
+
+	await t.throwsAsync(async () => lookahead0a.peek(0));
+	await t.throwsAsync(async () => lookahead0b.peek(0));
+	await t.throwsAsync(async () => lookahead0c.peek(0));
+	t.is(await lookahead1a.peek(0), 'c');
+	await t.throwsAsync(async () => lookahead1b.peek(0));
+	t.is(await lookahead2a.peek(0), 'd');
+	t.is(await lookahead2b.peek(0), 'c');
+
+	t.is(lookahead0a.position, 0);
+	t.is(lookahead0b.position, 0);
+	t.is(lookahead0c.position, 0);
+	t.is(lookahead1a.position, 2);
+	t.is(lookahead1b.position, 1);
+	t.is(lookahead2a.position, 3);
+	t.is(lookahead2b.position, 2);
+});
+
+test('inputReader.lookahead concurrent', async t => {
+	let read = 0;
+
+	const inputReader = new InputReaderImplementation(stringInputCompanion, (async function * () {
+		for (const character of 'abcdefgh') {
+			read++;
+			yield character;
+		}
+	})());
+
+	const lookahead1 = inputReader.lookahead();
+	const lookahead2 = inputReader.lookahead();
+	const lookahead3 = inputReader.lookahead();
+
+	const peeks = await Promise.all([
+		lookahead1.peek(0),
+		lookahead2.peek(0),
+		lookahead3.peek(0),
+	]);
+
+	const positions = [
+		lookahead1.position,
+		lookahead2.position,
+		lookahead3.position,
+	];
+
+	t.deepEqual(peeks, [ 'a', 'a', 'a' ]);
+	t.deepEqual(positions, [ 0, 0, 0 ]);
+	t.is(read, 1);
+});
+
+test('inputReader.lookahead skip position', async t => {
+	let read = 0;
+
+	const inputReader = new InputReaderImplementation(stringInputCompanion, (async function * () {
+		for (const character of 'abcdefgh') {
+			read++;
+			yield character;
+		}
+	})());
+
+	inputReader.skip(1);
+
+	const lookahead = inputReader.lookahead();
+
+	lookahead.skip(1);
+
+	const lookahead1 = lookahead.lookahead();
+
+	lookahead1.skip(1);
+
+	t.is(inputReader.position, 1);
+	t.is(lookahead.position, 2);
+	t.is(lookahead1.position, 3);
+
+	t.is(await inputReader.peek(0), 'b');
+	t.is(await lookahead.peek(0), 'c');
+	t.is(await lookahead1.peek(0), 'd');
+});

package/src/inputReader.ts

@@ -0,0 +1,159 @@
+import PromiseMutex from 'p-mutex';
+import invariant from 'invariant';
+import { type SequenceBuffer, SequenceBufferImplementation } from './sequenceBuffer.js';
+import { type InputCompanion } from './inputCompanion.js';
+import { parserImplementationInvariant } from './parserImplementationInvariant.js';
+
+export type InputReader<Sequence, Element> = {
+	get position(): number;
+
+	peek(offset: number): Promise<Element | undefined>;
+	skip(offset: number): void;
+
+	lookahead(): InputReader<Sequence, Element>;
+};
+
+let inputReaderId = 0;
+
+export class InputReaderImplementation<Sequence, Element> implements InputReader<Sequence, Element> {
+	private readonly _id = inputReaderId++;
+
+	private _position = 0;
+	private _uncommitedSkipOffset = 0;
+
+	private readonly _promiseMutex = new PromiseMutex();
+
+	private readonly _sequenceBuffer: SequenceBuffer<Sequence, Element>;
+
+	constructor(
+		private readonly _inputCompanion: InputCompanion<Sequence, Element>,
+		private readonly _inputAsyncIterator: AsyncIterator<Sequence>,
+	) {
+		this._sequenceBuffer = new SequenceBufferImplementation<Sequence, Element>(this._inputCompanion);
+	}
+
+	get [Symbol.toStringTag]() {
+		return [
+			'InputReader',
+			this._id,
+			this.position,
+		].join(' ');
+	}
+
+	get position() {
+		return this._position;
+	}
+
+	async peek(offset: number): Promise<Element | undefined> {
+		parserImplementationInvariant(offset >= 0, 'offset >= 0');
+
+		offset += this._uncommitedSkipOffset;
+
+		const element = this._sequenceBuffer.peek(offset);
+
+		if (element !== undefined) {
+			return element;
+		}
+
+		return this._promiseMutex.withLock(async () => {
+			while (true) {
+				const element = this._sequenceBuffer.peek(offset);
+
+				if (element !== undefined) {
+					return element;
+				}
+
+				const inputIteratorResult = await this._inputAsyncIterator.next();
+
+				if (inputIteratorResult.done) {
+					return undefined;
+				}
+
+				parserImplementationInvariant(
+					this._inputCompanion.is(inputIteratorResult.value),
+					[
+						'Input iterator result value (%s) is of unexpected type.',
+						'Expected a sequence (a chunk of input) recognized by the input companion (%s).',
+						'You may have provided a wrong input companion for the input.',
+					],
+					inputIteratorResult.value,
+					this._inputCompanion.constructor.name,
+				);
+
+				this._sequenceBuffer.push(inputIteratorResult.value);
+			}
+		});
+	}
+
+	skip(offset: number) {
+		parserImplementationInvariant(offset >= 0, 'offset >= 0');
+
+		this._position += offset;
+
+		if (this._promiseMutex.isLocked) {
+			this._uncommitedSkipOffset += offset;
+		} else {
+			this._sequenceBuffer.skip(offset + this._uncommitedSkipOffset);
+			this._uncommitedSkipOffset = 0;
+		}
+	}
+
+	lookahead(): InputReader<Sequence, Element> {
+		return new InputReaderLookaheadImplementation(this);
+	}
+}
+
+class InputReaderLookaheadImplementation<Sequence, Element> implements InputReader<Sequence, Element> {
+	private _initialInputReaderPosition = 0;
+	private _offset = 0;
+
+	constructor(
+		private readonly _inputReader: InputReaderImplementation<Sequence, Element>,
+	) {
+		this._initialInputReaderPosition = this._inputReader.position;
+	}
+
+	get [Symbol.toStringTag]() {
+		return [
+			'InputReaderLookahead',
+			this._inputReader.toString(),
+			this.position,
+		].join(' ');
+	}
+
+	get position() {
+		return this._initialInputReaderPosition + this._offset;
+	}
+
+	async peek(offset: number): Promise<Element | undefined> {
+		const inputReaderMovedForward = this._inputReader.position - this._initialInputReaderPosition;
+
+		this._initialInputReaderPosition = this._inputReader.position;
+		this._offset -= inputReaderMovedForward;
+
+		return this._inputReader.peek(this._offset + offset);
+	}
+
+	skip(offset: number) {
+		parserImplementationInvariant(offset >= 0, 'offset >= 0');
+
+		this._offset += offset;
+	}
+
+	lookahead(): InputReader<Sequence, Element> {
+		const lookahead = new InputReaderLookaheadImplementation(this._inputReader);
+
+		const offset = this.position - lookahead.position;
+
+		lookahead.skip(offset);
+
+		invariant(
+			this.position === lookahead.position,
+			'this.position (%s) === lookahead.position (%s)',
+			this.position,
+			lookahead.position,
+		);
+
+		return lookahead;
+	}
+}

package/src/invariantDefined.ts

@@ -0,0 +1,6 @@
+import invariant from 'invariant';
+
+export function invariantDefined<T>(value: T, format: string, ...extra: any[]): Exclude<T, undefined> {
+	invariant(value !== undefined, format, ...extra);
+	return value as any;
+}

package/src/invariantIdentity.ts

@@ -0,0 +1,8 @@
+import invariant from 'invariant';
+
+type Falsy = '' | 0 | false | undefined ;
+
+export function invariantIdentity<T>(value: T, format: string, ...extra: any[]): Exclude<T, Falsy> {
+	invariant(value, format, ...extra);
+	return value as any;
+}

package/src/jsonParser.test.ts

@@ -0,0 +1,26 @@
+import { testProp, fc } from '@fast-check/ava';
+import { jsonValueParser } from './jsonParser.js';
+import { runParser } from './parser.js';
+import { arbitrarilySlicedAsyncIterator } from './arbitrarilySlicedAsyncInterator.js';
+import { stringInputCompanion } from './inputCompanion.js';
+
+testProp(
+	'json',
+	[
+		arbitrarilySlicedAsyncIterator(
+			fc.tuple(fc.json(), fc.nat())
+				.map(([ jsonString, indent ]) => JSON.stringify(JSON.parse(jsonString), null, indent)),
+		),
+	],
+	async (t, [ jsonString, jsonStringChunkIterator ]) => {
+		const actual = await runParser(jsonValueParser, jsonStringChunkIterator, stringInputCompanion, {
+			errorJoinMode: 'none',
+		});
+		const expected = JSON.parse(jsonString);
+
+		t.deepEqual(actual, expected);
+	},
+	{
+		verbose: true,
+	},
+);