@futpib/parser 1.0.0

package/src/arbitraryFileSystemEntry.ts

@@ -0,0 +1,36 @@
+import * as fc from 'fast-check';
+
+type FileSystemDirectory = {
+	type: 'directory';
+	name: string;
+	entries: FileSystemEntry[];
+};
+
+type FileSystemFile = {
+	type: 'file';
+	name: string;
+	content: Uint8Array;
+};
+
+export type FileSystemEntry =
+	| FileSystemFile
+	| FileSystemDirectory
+;
+
+export const arbitraryFileSystemEntry = fc.letrec((tie) => ({
+	entry: fc.oneof<[
+		fc.Arbitrary<FileSystemFile>,
+		fc.Arbitrary<FileSystemDirectory>,
+	]>(
+		fc.record<FileSystemFile>({
+			type: fc.constant('file'),
+			name: fc.string(),
+			content: fc.uint8Array(),
+		}),
+		fc.record<FileSystemDirectory>({
+			type: fc.constant('directory'),
+			name: fc.string(),
+			entries: fc.array(tie('entry') as fc.Arbitrary<FileSystemEntry>),
+		}),
+	),
+})).entry;

package/src/arbitraryZip.ts

@@ -0,0 +1,132 @@
+import * as fc from 'fast-check';
+import { Zip, ZipDirectoryEntry, ZipEntry, ZipFileEntry } from './zip.js';
+import { arbitraryDosDateTime } from './arbitraryDosDateTime.js';
+import { createArbitraryZipPermissions } from './arbitraryZipPermissions.js';
+import invariant from 'invariant';
+
+const DOS_DIRECTORY_FLAG = 0b00010000;
+
+const arbitraryPath = fc.string({ minLength: 1 }).filter(path => {
+	const pathSegments = path.split('/');
+	const pathHasEmptySegments = pathSegments.some(segment => segment.length === 0);
+
+	if (pathHasEmptySegments) {
+		return false;
+	}
+
+	return true;
+});
+
+const createArbitraryZipEntry = (platform: 'unix' | 'dos') => fc.oneof<[
+	fc.Arbitrary<ZipFileEntry>,
+	fc.Arbitrary<ZipDirectoryEntry>,
+]>(
+	fc.record<ZipFileEntry>({
+		type: fc.constant('file'),
+		path: arbitraryPath,
+		date: arbitraryDosDateTime,
+		comment: fc.string(),
+		permissions: createArbitraryZipPermissions(platform),
+		compression: fc.oneof(
+			fc.constant('store' as const),
+			fc.constant('deflate' as const),
+		),
+		content: fc.uint8Array(),
+	}).filter(zipFileEntry => {
+		if (
+			zipFileEntry.content.length === 0
+			&& zipFileEntry.compression === 'deflate'
+		) {
+			return false;
+		}
+
+		if (
+			zipFileEntry.permissions.type === 'dos'
+				&& zipFileEntry.permissions.dosPermissions & DOS_DIRECTORY_FLAG
+		) {
+			return false;
+		}
+
+		return true;
+	}),
+	fc.record<ZipDirectoryEntry>({
+		type: fc.constant('directory'),
+		path: arbitraryPath,
+		date: arbitraryDosDateTime,
+		comment: fc.string(),
+		permissions: createArbitraryZipPermissions(platform),
+	}).filter(zipDirectoryEntry => {
+		if (
+			zipDirectoryEntry.permissions.type === 'dos'
+				&& !(zipDirectoryEntry.permissions.dosPermissions & DOS_DIRECTORY_FLAG)
+		) {
+			return false;
+		}
+
+		return true;
+	}),
+);
+
+const createArbitraryZipEntries = (platform: 'unix' | 'dos') => (
+	fc
+		.array(createArbitraryZipEntry(platform))
+		.map(entries => {
+			const seenPaths = new Set<string>();
+			const seenDirectoryPaths = new Set<string>();
+
+			const normalizedEntries: typeof entries = [];
+
+			for (const entry of entries) {
+				if (seenPaths.has(entry.path)) {
+					continue;
+				}
+
+				seenPaths.add(entry.path);
+
+				if (entry.type === 'directory') {
+					seenDirectoryPaths.add(entry.path);
+
+					continue;
+				}
+
+				invariant(entry.type === 'file', 'Unexpected entry type %s.', entry.type);
+
+				const directories = entry.path.split('/').slice(0, -1);
+
+				for (const depth of Array.from({ length: directories.length }).map((_, index) => index)) {
+					const directoryPath = directories.slice(0, depth + 1).join('/');
+
+					if (directoryPath.length === 0) {
+						continue;
+					}
+
+					if (!seenDirectoryPaths.has(directoryPath)) {
+						normalizedEntries.push({
+							type: 'directory',
+							path: directoryPath,
+							date: entry.date,
+							comment: '',
+							permissions: entry.permissions.type === 'dos' ? {
+								type: 'dos',
+								dosPermissions: entry.permissions.dosPermissions | DOS_DIRECTORY_FLAG,
+							} : entry.permissions,
+						});
+
+						seenDirectoryPaths.add(directoryPath);
+					}
+				}
+
+				normalizedEntries.push(entry);
+			}
+
+			return normalizedEntries;
+		})
+);
+
+export const arbitraryZip = fc.oneof(
+	fc.constant('unix' as const),
+	fc.constant('dos' as const),
+).chain(platform => fc.record<Zip>({
+	comment: fc.string(),
+	entries: createArbitraryZipEntries(platform),
+}));

package/src/arbitraryZipPermissions.ts

@@ -0,0 +1,25 @@
+import * as fc from 'fast-check';
+import { ZipDosPermissions, ZipUnixPermissions } from './zip.js';
+
+const arbitraryZipUnixPermissions = fc.record<ZipUnixPermissions>({
+	type: fc.constant('unix'),
+	unixPermissions: (
+		fc.nat({ max: 0b0000000111111111 })
+			.filter((unixPermissions) => unixPermissions > 0)
+	),
+});
+
+const arbitraryZipDosPermissions = fc.record<ZipDosPermissions>({
+	type: fc.constant('dos'),
+	dosPermissions: (
+		fc.nat({ max: 0b00111111 })
+	),
+});
+
+export const createArbitraryZipPermissions = (type: 'unix' | 'dos') => {
+	if (type === 'unix') {
+		return arbitraryZipUnixPermissions;
+	}
+
+	return arbitraryZipDosPermissions;
+};

package/src/arbitraryZipStream.ts

@@ -0,0 +1,60 @@
+import JSZip from 'jszip';
+import { ZipEntry } from './zip.js';
+import { arbitraryZip } from './arbitraryZip.js';
+
+function addZipEntryToZip(zip: JSZip, zipEntry: ZipEntry) {
+	const options = {
+		comment: zipEntry.comment,
+		date: zipEntry.date,
+		unixPermissions: zipEntry.permissions.type === 'unix' ? zipEntry.permissions.unixPermissions : undefined,
+		dosPermissions: zipEntry.permissions.type === 'dos' ? zipEntry.permissions.dosPermissions : undefined,
+	};
+
+	if (zipEntry.type === 'file') {
+		zip.file<'uint8array'>(zipEntry.path, zipEntry.content, {
+			compression: zipEntry.compression.toUpperCase() as any,
+			compressionOptions: undefined,
+			binary: true,
+			...options,
+		});
+	} else {
+		zip.file(zipEntry.path, null, {
+			dir: true,
+			...options,
+		});
+	}
+}
+
+export const arbitraryZipStream = arbitraryZip.map(zip => {
+	const jsZip = new JSZip();
+
+	for (const zipEntry of zip.entries) {
+		addZipEntryToZip(jsZip, zipEntry);
+	}
+
+	const zipInternalStream = jsZip.generateInternalStream({
+		type: 'uint8array',
+		comment: zip.comment,
+		platform: zip.entries.at(0)?.permissions.type.toUpperCase() as any,
+	});
+
+	const zipStream = new ReadableStream<Uint8Array>({
+		start(controller) {
+			zipInternalStream.on('data', (chunk: Uint8Array) => {
+				controller.enqueue(chunk);
+			});
+
+			zipInternalStream.on('end', () => {
+				controller.close();
+			});
+
+			zipInternalStream.on('error', (error: Error) => {
+				controller.error(error);
+			});
+
+			zipInternalStream.resume();
+		},
+	});
+
+	return [ zip, zipStream ] as const;
+});

package/src/arrayParser.test.ts

@@ -0,0 +1,11 @@
+import test from 'ava';
+import { createArrayParser } from './arrayParser.js';
+import { Parser, runParser } from './parser.js';
+import { stringInputCompanion } from './inputCompanion.js';
+
+test('does not loop forever with a child parser that does not consume anything', async t => {
+	const parser: Parser<undefined[], string> = createArrayParser(async () => undefined);
+	const result = await runParser(parser, 'foo', stringInputCompanion);
+
+	t.deepEqual(result, []);
+});

package/src/arrayParser.ts

@@ -0,0 +1,35 @@
+import { getParserName, Parser, setParserName } from "./parser.js";
+import { ParserParsingFailedError } from "./parserError.js";
+
+export const createArrayParser = <ElementOutput, Sequence>(
+	elementParser: Parser<ElementOutput, Sequence>,
+): Parser<ElementOutput[], Sequence> => {
+	const arrayParser: 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) {
+					return elements;
+				}
+				elements.push(element);
+				elementParserContext.unlookahead();
+			} catch (error) {
+				if (error instanceof ParserParsingFailedError) {
+					return elements;
+				}
+
+				throw error;
+			} finally {
+				elementParserContext.dispose();
+			}
+		}
+	};
+
+	setParserName(arrayParser, getParserName(elementParser, 'anonymousArrayChild') + '*');
+
+	return arrayParser;
+};

package/src/bsonParser.test.ts

@@ -0,0 +1,37 @@
+import { testProp, fc } from '@fast-check/ava';
+import { BSON } from 'bson';
+import { bsonDocumentParser } from './bsonParser.js';
+import { arbitrarilySlicedAsyncIterator } from './arbitrarilySlicedAsyncInterator.js';
+import { runParser } from './parser.js';
+import { uint8ArrayInputCompanion } from './inputCompanion.js';
+
+testProp(
+	'bson',
+	[
+		arbitrarilySlicedAsyncIterator(
+			fc
+				.json()
+				.filter(jsonString => {
+					// BSON.serialize does not support non-object top-level values
+					const jsonValue = JSON.parse(jsonString);
+
+					return (
+						jsonValue !== null
+							&& typeof jsonValue === 'object'
+							&& !Array.isArray(jsonValue)
+					);
+				})
+				.map(jsonString => BSON.serialize(JSON.parse(jsonString))),
+		),
+	],
+	async (t, [ bsonUint8Array, bsonUint8ArrayChunkIterator ]) => {
+		const expected = BSON.deserialize(bsonUint8Array);
+
+		const actual = await runParser(bsonDocumentParser, bsonUint8ArrayChunkIterator, uint8ArrayInputCompanion);
+
+		t.deepEqual(actual, expected);
+	},
+	{
+		verbose: true,
+	},
+);

package/src/bsonParser.ts

@@ -0,0 +1,131 @@
+import { type JsonObject, type JsonValue } from 'type-fest';
+import { getParserName, setParserName, type Parser } from './parser.js';
+import { invariantDefined } from './invariantDefined.js';
+import { createFixedLengthSequenceParser } from './fixedLengthSequenceParser.js';
+import { promiseCompose } from './promiseCompose.js';
+import { createTupleParser } from './tupleParser.js';
+import { createSkipParser } from './skipParser.js';
+import { createParserAccessorParser } from './parserAccessorParser.js';
+import { createTerminatedArrayParser } from './terminatedArrayParser.js';
+import { createElementParser } from './elementParser.js';
+import { createExactElementParser } from './exactElementParser.js';
+import { createUnionParser } from './unionParser.js';
+import { parserCreatorCompose } from './parserCreatorCompose.js';
+
+const createFixedLengthBufferParser = (length: number): Parser<Buffer, Uint8Array> => promiseCompose(createFixedLengthSequenceParser<Uint8Array>(length), sequence => Buffer.from(sequence));
+
+const buffer1Parser = createFixedLengthBufferParser(1);
+const buffer4Parser = createFixedLengthBufferParser(4);
+const buffer8Parser = createFixedLengthBufferParser(8);
+
+const elementParser: Parser<number, Uint8Array> = createElementParser();
+
+const nullByteParser: Parser<number, Uint8Array> = createExactElementParser(0);
+
+const cstringParser: Parser<string, Uint8Array> = promiseCompose(
+	createTerminatedArrayParser(
+		parserCreatorCompose(
+			() => elementParser,
+			(byte: number) => async parserContext => parserContext.invariant(byte, 'Expected non-null byte'),
+		)(),
+		nullByteParser,
+	),
+	([sequence]) => Buffer.from(sequence).toString('utf8'),
+);
+
+const doubleParser: Parser<number, Uint8Array> = promiseCompose(buffer8Parser, buffer => buffer.readDoubleLE(0));
+const int32Parser: Parser<number, Uint8Array> = promiseCompose(buffer4Parser, buffer => buffer.readInt32LE(0));
+const uint32Parser: Parser<number, Uint8Array> = promiseCompose(buffer4Parser, buffer => buffer.readUInt32LE(0));
+
+const createFixedLengthStringParser = (length: number): Parser<string, Uint8Array> => promiseCompose(
+	createFixedLengthBufferParser(length),
+	buffer => buffer.toString('utf8'),
+);
+
+const createFixedLengthNullTerminatedStringParser = (lengthWihoutNullTerminator: number): Parser<string, Uint8Array> => promiseCompose(
+	createTupleParser([
+		createFixedLengthStringParser(lengthWihoutNullTerminator),
+		nullByteParser,
+	]),
+	([string]) => string,
+);
+
+const bsonStringParser: Parser<string, Uint8Array> = async parserContext => {
+	const stringSize = await uint32Parser(parserContext);
+
+	return createFixedLengthNullTerminatedStringParser(stringSize - 1)(parserContext);
+};
+
+const bsonArrayParser = promiseCompose(
+	createTupleParser([
+		createSkipParser(4),
+		createParserAccessorParser(() => bsonElementListParser),
+	]),
+	([ _, elements ]) => elements.map(([ _, value ]) => value),
+);
+
+const bsonBooleanParser: Parser<boolean, Uint8Array> = async parserContext => {
+	const booleanValue = invariantDefined(await parserContext.read(0), 'Unexpected end of input');
+
+	return booleanValue === 1;
+};
+
+const int8Parser: Parser<number, Uint8Array> = promiseCompose(buffer1Parser, buffer => buffer.readInt8(0));
+
+const createExactInt8Parser = (value: number): Parser<number, Uint8Array> => parserCreatorCompose(
+	() => int8Parser,
+	actualValue => async parserContext => {
+		parserContext.invariant(actualValue === value, 'Expected %s, got %s', value, actualValue);
+
+		return actualValue;
+	},
+)();
+
+const createBsonElementParser = <ValueOutput>(
+	elementType: number,
+	valueParser: Parser<ValueOutput, Uint8Array>,
+): Parser<[ string, ValueOutput ], Uint8Array> => setParserName(
+	promiseCompose(
+		createTupleParser([
+			createExactInt8Parser(elementType),
+			cstringParser,
+			valueParser,
+		]),
+		([ _, elementName, elementValue ]) => [ elementName, elementValue ],
+	),
+	`bsonElementParser(${elementType}, ${getParserName(valueParser)})`,
+);
+
+const bsonDoubleElementParser = createBsonElementParser(1, doubleParser);
+const bsonStringElementParser = createBsonElementParser(2, bsonStringParser);
+const bsonDocumentElementParser = createBsonElementParser(3, createParserAccessorParser(() => bsonDocumentParser));
+const bsonArrayElementParser = createBsonElementParser(4, bsonArrayParser);
+const bsonBooleanElementParser = createBsonElementParser(8, bsonBooleanParser);
+const bsonNullElementParser = createBsonElementParser(10, async () => null);
+const bsonInt32ElementParser = createBsonElementParser(16, int32Parser);
+
+const bsonElementParser: Parser<[ string, JsonValue ], Uint8Array> = createUnionParser([
+	bsonDoubleElementParser,
+	bsonStringElementParser,
+	bsonDocumentElementParser,
+	bsonArrayElementParser,
+	bsonBooleanElementParser,
+	bsonNullElementParser,
+	bsonInt32ElementParser,
+]);
+
+const bsonElementListParser: Parser<Array<[ string, JsonValue ]>, Uint8Array> = promiseCompose(
+	createTerminatedArrayParser(
+		bsonElementParser,
+		nullByteParser,
+	),
+	([elements]) => elements,
+);
+
+export const bsonDocumentParser: Parser<JsonObject, Uint8Array> = promiseCompose(
+	createTupleParser([
+		createSkipParser(4),
+		bsonElementListParser,
+	]),
+	([ _, elements ]) => Object.fromEntries(elements),
+);

package/src/debugLogParser.ts

@@ -0,0 +1,51 @@
+import { getParserName, Parser, setParserName } from "./parser.js";
+
+export const createDebugLogParser = <Output, Sequence>(
+	childParser: Parser<Output, Sequence>,
+): Parser<Output, Sequence> => {
+	let idCounter = 0;
+
+	const debugLogParser: typeof childParser = async parserContext => {
+		const id = idCounter++;
+		const initialPosition = parserContext.position;
+
+		console.debug(
+			'%s %s: started (position: %s)',
+			getParserName(childParser),
+			id,
+			initialPosition,
+		);
+
+		try {
+			const result = await childParser(parserContext);
+
+			console.debug(
+				'%s %s: finished (position: %s, consumed: %s): %o',
+				getParserName(childParser),
+				id,
+				parserContext.position,
+				parserContext.position - initialPosition,
+				result,
+			);
+
+			return result;
+		} catch (error) {
+			console.debug(
+				'%s %s: failed (position: %s, consumed: %s): %o',
+				getParserName(childParser),
+				id,
+				parserContext.position,
+				parserContext.position - initialPosition,
+				error,
+			);
+
+			throw error;
+		}
+	};
+
+	return setParserName(debugLogParser, [
+		'debugLog(',
+		getParserName(childParser),
+		')',
+	].join(''));
+};

package/src/disjunctionParser.ts

@@ -0,0 +1,55 @@
+import { getParserName, setParserName, type Parser } from './parser.js';
+import { ParserParsingFailedError } from './parserError.js';
+import { parserImplementationInvariant } from './parserImplementationInvariant.js';
+
+export const createDisjunctionParser = <
+	Output,
+	Sequence,
+>(
+	childParsers: Array<Parser<any, Sequence, any>>,
+): Parser<Output, Sequence, unknown> => {
+	parserImplementationInvariant(childParsers.length > 0, 'Disjunction parser must have at least one child parser.');
+
+	const disjunctionParser: Parser<Output, Sequence, unknown> = async parserContext => {
+		const parserParsingFailedErrors: ParserParsingFailedError[] = [];
+
+		for (const childParser of childParsers) {
+			const childParserContext = parserContext.lookahead({
+				debugName: getParserName(childParser, 'anonymousDisjunctionChild'),
+			});
+
+			const [ childParserResult ] = await Promise.allSettled([ childParser(childParserContext) ]);
+
+			if (childParserResult.status === 'fulfilled') {
+				const successfulParserOutput = childParserResult.value;
+
+				childParserContext.unlookahead();
+				childParserContext.dispose();
+
+				return successfulParserOutput;
+			}
+
+			const error = childParserResult.reason;
+
+			if (error instanceof ParserParsingFailedError) {
+				parserParsingFailedErrors.push(error);
+			} else {
+				throw error;
+			}
+		}
+
+		parserContext.invariantJoin(
+			false,
+			parserParsingFailedErrors,
+			'No disjunction child parser succeeded.',
+		);
+	};
+
+	const name = [
+		'(',
+		...childParsers.map(childParser => getParserName(childParser, 'anonymousDiscjunctionChild')).join('|'),
+		')',
+	].join('');
+
+	return setParserName(disjunctionParser, name);
+};

package/src/elementParser.ts

@@ -0,0 +1,4 @@
+import { Parser } from "./parser.js";
+import { DeriveSequenceElement } from "./sequence.js";
+
+export const createElementParser = <Sequence, Element = DeriveSequenceElement<Sequence>>(): Parser<Element, Sequence, Element> => parserContext => parserContext.read(0);

package/src/endOfInputParser.ts

@@ -0,0 +1,11 @@
+import { Parser } from "./parser.js";
+import { DeriveSequenceElement } from "./sequence.js";
+
+export const createEndOfInputParser = <Sequence, Element = DeriveSequenceElement<Sequence>>(): Parser<void, Sequence, Element> => async parserContext => {
+	parserContext.invariant(
+		await parserContext.peek(0) === undefined,
+		'Expected end of input.'
+	);
+}
+
+export const endOfInputParser = createEndOfInputParser<any, any>();

package/src/exactElementParser.ts

@@ -0,0 +1,20 @@
+import { type Parser } from './parser.js';
+import { DeriveSequenceElement } from './sequence.js';
+
+export const createExactElementParser = <
+	Sequence,
+	Element = DeriveSequenceElement<Sequence>,
+>(element: Element): Parser<Element, Sequence, Element> => async parserContext => {
+	const actualElement = await parserContext.peek(0);
+
+	parserContext.invariant(
+		actualElement === element,
+		'Expected %s, got %s',
+		element,
+		actualElement,
+	);
+
+	parserContext.skip(1);
+
+	return element;
+};

package/src/exactSequenceParser.ts

@@ -0,0 +1,27 @@
+import { inspect } from 'util';
+import { setParserName, type Parser } from './parser.js';
+
+export const createExactSequenceParser = <Sequence>(sequence: Sequence) => {
+	const exactSequenceParser: Parser<Sequence, Sequence, unknown> = async parserContext => {
+		const length = parserContext.length(sequence);
+
+		for (let index = 0; index < length; index++) {
+			const element = await parserContext.read(0);
+			const expectedElement = parserContext.at(sequence, index);
+
+			parserContext.invariant(
+				element === expectedElement,
+				'Expected "%s", got "%s", at index %s',
+				expectedElement,
+				element,
+				index,
+			);
+		}
+
+		return sequence;
+	};
+
+	setParserName(exactSequenceParser, inspect(sequence));
+
+	return exactSequenceParser;
+}

package/src/fixedLengthSequenceParser.ts

@@ -0,0 +1,24 @@
+import { setParserName, type Parser } from './parser.js';
+import { parserImplementationInvariant } from './parserImplementationInvariant.js';
+
+export const createFixedLengthSequenceParser = <Sequence>(lengthInput: bigint | number) => {
+	const length = BigInt(lengthInput);
+
+	parserImplementationInvariant(length >= 0n, 'Length must be non-negative got %s.', length);
+
+	const fixedLengthSequenceParser: Parser<Sequence, Sequence, unknown> = async parserContext => {
+		const elements = [];
+
+		for (let i = 0n; i < length; i++) {
+			const element = await parserContext.read(0);
+
+			elements.push(element);
+		}
+
+		return parserContext.from(elements);
+	};
+
+	setParserName(fixedLengthSequenceParser, `.{${length}}`);
+
+	return fixedLengthSequenceParser;
+};

package/src/index.test.ts

@@ -0,0 +1,3 @@
+import test from 'ava';
+
+test.todo('TODO');