@futpib/parser 1.0.0 → 1.0.1

package/src/unparser.test.ts

@@ -0,0 +1,221 @@
+import test from 'ava';
+import * as fc from 'fast-check';
+import { runUnparser, Unparser } from './unparser.js';
+import { stringUnparserOutputCompanion } from './unparserOutputCompanion.js';
+import { testProp } from '@fast-check/ava';
+
+test('writeLater', async t => {
+	const stringToBeWrittenBefore = 'before writeLater\n';
+	const stringToBeWrittenLater = 'written later\n';
+	const stringToBeWrittenAfter = 'after writeLater\n';
+
+	let expectedPositionA: number | undefined;
+	let expectedPositionB: number | undefined;
+
+	let actualPositionAFromWithinWriteLater: number | undefined;
+	let actualPositionBFromWithinWriteLater: number | undefined;
+
+	const unparser: Unparser<void, string> = async function * (_input, unparserContext) {
+		yield stringToBeWrittenBefore
+
+		expectedPositionA = unparserContext.position;
+
+		const writeLater = yield * unparserContext.writeLater(stringToBeWrittenLater.length);
+
+		expectedPositionB = unparserContext.position;
+
+		yield stringToBeWrittenAfter;
+
+		yield * unparserContext.writeEarlier(writeLater, async function * (_input, unparserContext) {
+			actualPositionAFromWithinWriteLater = unparserContext.position;
+
+			yield stringToBeWrittenLater;
+
+			actualPositionBFromWithinWriteLater = unparserContext.position;
+		}, undefined);
+	};
+
+	const stringsAsyncIterable = runUnparser(unparser, undefined, stringUnparserOutputCompanion);
+
+	const strings: string[] = [];
+
+	for await (const string of stringsAsyncIterable) {
+		strings.push(string);
+	}
+
+	const string = strings.join('');
+
+	t.is(string, stringToBeWrittenBefore + stringToBeWrittenLater + stringToBeWrittenAfter);
+
+	t.is(actualPositionAFromWithinWriteLater, expectedPositionA, 'position a');
+	t.is(actualPositionBFromWithinWriteLater, expectedPositionB, 'position b');
+
+	t.is(expectedPositionA, stringToBeWrittenBefore.length);
+	t.is(expectedPositionB, stringToBeWrittenBefore.length + stringToBeWrittenLater.length);
+});
+
+test('writeLater one deep', async t => {
+	const unparser: Unparser<void, string> = async function * (_input, unparserContext) {
+		yield '(';
+		const writeLaterA = yield * unparserContext.writeLater(3);
+		yield ')';
+
+		yield * unparserContext.writeEarlier(writeLaterA, async function * (_input, unparserContext) {
+			yield '[';
+			const writeLaterB = yield * unparserContext.writeLater(1);
+			yield ']';
+
+			yield * unparserContext.writeEarlier(writeLaterB, async function * (_input, unparserContext) {
+				yield 'a';
+			}, undefined);
+		}, undefined);
+	};
+
+	const stringsAsyncIterable = runUnparser(unparser, undefined, stringUnparserOutputCompanion);
+
+	const strings: string[] = [];
+
+	for await (const string of stringsAsyncIterable) {
+		strings.push(string);
+	}
+
+	const string = strings.join('');
+
+	t.is(string, '([a])');
+});
+
+test('writeLater deep', async t => {
+	const unparser: Unparser<void, string> = async function * (_input, unparserContext) {
+		yield '(';
+		const writeLaterA = yield * unparserContext.writeLater(5);
+		yield ')';
+
+		let writeLaterC: typeof writeLaterA;
+
+		yield * unparserContext.writeEarlier(writeLaterA, async function * (_input, unparserContext) {
+			yield '[';
+			const writeLaterB = yield * unparserContext.writeLater(3);
+			yield ']';
+
+			yield * unparserContext.writeEarlier(writeLaterB, async function * (_input, unparserContext) {
+				yield '{';
+				writeLaterC = yield * unparserContext.writeLater(1);
+				yield '}';
+			}, undefined);
+		}, undefined);
+
+		yield * unparserContext.writeEarlier(writeLaterC!, async function * (_input, unparserContext) {
+			yield 'a';
+		}, undefined);
+
+		yield 'z';
+	};
+
+	const stringsAsyncIterable = runUnparser(unparser, undefined, stringUnparserOutputCompanion);
+
+	const strings: string[] = [];
+
+	for await (const string of stringsAsyncIterable) {
+		strings.push(string);
+	}
+
+	const string = strings.join('');
+
+	t.is(string, '([{a}])z');
+});
+
+testProp(
+	'writeLater positions and lengths',
+	[
+		fc.array(
+			fc.oneof(
+				fc.array(
+					fc.oneof(
+						fc.array(
+							fc.string(),
+						),
+						fc.string(),
+					),
+				),
+				fc.string(),
+			),
+		),
+	],
+	async (t, stringArray3) => {
+		const numberUnparser: Unparser<number, string> = async function * (input, unparserContext) {
+			yield input.toString().padStart(8, '0');
+		};
+
+		const createLengthPrefixedUnparser = <T>(
+			unparser: Unparser<T, string>,
+		): Unparser<T, string> => {
+			return async function * (input, unparserContext) {
+				const length = yield * unparserContext.writeLater(8);
+				yield * unparser(input, unparserContext);
+				yield * unparserContext.writeEarlier(length, numberUnparser, unparserContext.position - length.positionEnd);
+			};
+		};
+
+		const unparser0: Unparser<string, string> = createLengthPrefixedUnparser(async function * (input, unparserContext) {
+			yield input;
+		});
+
+		const unparser1: Unparser<string[], string> = createLengthPrefixedUnparser(async function * (input, unparserContext) {
+			for (const string of input) {
+				yield * unparser0(string, unparserContext);
+			}
+		});
+
+		const unparser2: Unparser<(string | string[])[], string> = createLengthPrefixedUnparser(async function * (input, unparserContext) {
+			for (const stringArray2 of input) {
+				if (typeof stringArray2 === 'string') {
+					yield * unparser0(stringArray2, unparserContext);
+				} else {
+					yield * unparser1(stringArray2, unparserContext);
+				}
+			}
+		});
+
+		const unparser3: Unparser<(string | (string | string[])[])[], string> = createLengthPrefixedUnparser(async function * (input, unparserContext) {
+			for (const stringArray3 of input) {
+				if (typeof stringArray3 === 'string') {
+					yield * unparser0(stringArray3, unparserContext);
+				} else {
+					yield * unparser2(stringArray3, unparserContext);
+				}
+			}
+		});
+
+		const stringsAsyncIterable = runUnparser(unparser3, stringArray3, stringUnparserOutputCompanion);
+
+		const strings: string[] = [];
+
+		for await (const string of stringsAsyncIterable) {
+			strings.push(string);
+		}
+
+		const actualString = strings.join('');
+
+		type DeepArray<T> = T | DeepArray<T>[];
+
+		function getExpectedString(stringArray: DeepArray<string>): string {
+			let expectedString = stringArray;
+
+			if (typeof stringArray !== 'string') {
+				expectedString = stringArray.map(getExpectedString).join('');
+			}
+
+			return [
+				expectedString.length.toString().padStart(8, '0'),
+				expectedString,
+			].join('');
+		}
+
+		const expectedString = getExpectedString(stringArray3);
+
+		t.deepEqual(actualString, expectedString);
+	},
+	{
+		verbose: true,
+	},
+);

package/src/unparser.ts

@@ -0,0 +1,209 @@
+import invariant from "invariant";
+import { DeriveSequenceElement } from "./sequence.js";
+import { UnparserContext, UnparserContextImplementation, WriteEarlier, WriteLater } from "./unparserContext.js";
+import { UnparserOutputCompanion } from "./unparserOutputCompanion.js";
+import { unparserImplementationInvariant } from "./unparserImplementationInvariant.js";
+
+type UnparserIterableValue<Sequence, Element> =
+	| Sequence
+	| Element
+	| WriteLater<Sequence, Element>
+	| WriteEarlier<Sequence, Element>
+;
+
+type UnparserIterableValue_<Sequence, Element> =
+	| Sequence
+	| WriteLater<Sequence, Element>
+	| WriteEarlier<Sequence, Element>
+;
+
+export type UnparserResult<Sequence, Element> = AsyncIterable<UnparserIterableValue<Sequence, Element>>;
+
+type UnparserResult_<Sequence, Element> = AsyncIterable<UnparserIterableValue_<Sequence, Element>>;
+
+export type Unparser<
+	Input,
+	Sequence,
+	Element = DeriveSequenceElement<Sequence>,
+> = (
+	input: Input,
+	unparserContext: UnparserContext<Sequence, Element>,
+) => UnparserResult<Sequence, Element>;
+
+async function * onYield<T>(asyncIterable: AsyncIterable<T>, onYield: (value: T) => void): AsyncIterable<T> {
+	for await (const value of asyncIterable) {
+		onYield(value);
+		yield value;
+	}
+}
+
+async function * elementsToSequences<
+	Sequence,
+	Element,
+>(
+	values: UnparserResult<Sequence, Element>,
+	unparserOutputCompanion: UnparserOutputCompanion<Sequence, Element>,
+): UnparserResult_<Sequence, Element> {
+	let elements: Element[] = [];
+
+	for await (const value of values) {
+		if (
+			value instanceof WriteLater
+				|| value instanceof WriteEarlier
+		) {
+			if (elements.length > 0) {
+				const sequence = unparserOutputCompanion.from(elements);
+				yield sequence;
+				elements = [];
+			}
+
+			yield value;
+		} else if (unparserOutputCompanion.is(value)) {
+			if (unparserOutputCompanion.length(value) === 0) {
+				continue;
+			}
+
+			if (elements.length > 0) {
+				const sequence = unparserOutputCompanion.from(elements);
+				yield sequence;
+				elements = [];
+			}
+
+			yield value;
+		} else {
+			elements.push(value);
+		}
+	}
+
+	if (elements.length > 0) {
+		const sequence = unparserOutputCompanion.from(elements);
+		yield sequence;
+	}
+}
+
+function wrapUnparserResult<Sequence, Element>(
+	unparserResult: UnparserResult<Sequence, Element>,
+	unparserContext: UnparserContextImplementation<Sequence, Element>,
+	unparserOutputCompanion: UnparserOutputCompanion<Sequence, Element>,
+): UnparserResult_<Sequence, Element> {
+	return onYield(
+		elementsToSequences(
+			unparserResult,
+			unparserOutputCompanion,
+		),
+		value => unparserContext.handleYield(value),
+	);
+}
+
+export async function * runUnparser<
+	Input,
+	Sequence,
+	Element = DeriveSequenceElement<Sequence>,
+>(
+	unparser: Unparser<Input, Sequence, Element>,
+	input: Input,
+	unparserOutputCompanion: UnparserOutputCompanion<Sequence, Element>,
+): AsyncIterable<Sequence> {
+	const unparserContext = new UnparserContextImplementation(unparserOutputCompanion);
+
+	const values = unparser(input, unparserContext);
+	const valuesWithoutElements = wrapUnparserResult(
+		values,
+		unparserContext,
+		unparserOutputCompanion,
+	);
+
+	const outputQueue: Array<WriteLater<Sequence, Element> | Sequence> = [];
+
+	type Iterator = AsyncIterator<UnparserIterableValue_<Sequence, Element>, void>;
+	type PushOutput = (value: Sequence | WriteLater<Sequence, Element>) => void;
+	type FinishOutput = () => void;
+
+	const iteratorStack: [ Iterator, PushOutput, FinishOutput ][] = [
+		[
+			valuesWithoutElements[Symbol.asyncIterator](),
+			value => outputQueue.push(value),
+			() => {},
+		],
+	];
+
+	while (true) {
+		while (
+			outputQueue.length > 0
+				&& !(outputQueue[0] instanceof WriteLater)
+		) {
+			yield outputQueue.shift() as Sequence;
+		}
+
+		if (iteratorStack.length === 0) {
+			break;
+		}
+
+		const [ iterator, pushOutput, finishOutput ] = iteratorStack[0];
+
+		const iteratorResult = await iterator.next();
+
+		if (iteratorResult.done) {
+			finishOutput();
+			iteratorStack.shift();
+			continue;
+		}
+
+		const { value } = iteratorResult;
+
+		if (value instanceof WriteEarlier) {
+			const { writeLater, unparserResult, unparserContext } = value;
+
+			invariant(
+				unparserContext instanceof UnparserContextImplementation,
+				'UnparserContext not an instance of UnparserContextImplementation.',
+			);
+
+			function getOutputQueueWriteLaterIndex() {
+				const outputQueueWriteLaterIndex = outputQueue.indexOf(writeLater);
+
+				unparserImplementationInvariant(
+					outputQueueWriteLaterIndex !== -1,
+					[
+						'WriteLater has already been written or was not yielded yet.',
+						'WriteLater stack: %s',
+						'End of WriteLater stack.',
+					],
+					writeLater.stack,
+				);
+
+				return outputQueueWriteLaterIndex;
+			}
+
+			const unparserResultWithoutElements = wrapUnparserResult(
+				unparserResult,
+				unparserContext,
+				unparserOutputCompanion,
+			);
+
+			const newPushOutput: PushOutput = value => {
+				const outputQueueWriteLaterIndex = getOutputQueueWriteLaterIndex();
+				outputQueue.splice(outputQueueWriteLaterIndex, 0, value);
+			};
+
+			const newFinishOutput: FinishOutput = () => {
+				const outputQueueWriteLaterIndex = getOutputQueueWriteLaterIndex();
+				const [ removedValue ] = outputQueue.splice(outputQueueWriteLaterIndex, 1);
+				invariant(
+					removedValue === writeLater,
+					'WriteLater was not removed from the output queue.',
+				);
+			};
+
+			iteratorStack.unshift([
+				unparserResultWithoutElements[Symbol.asyncIterator](),
+				newPushOutput,
+				newFinishOutput,
+			]);
+
+			continue;
+		}
+
+		pushOutput(value);
+	}
+}

package/src/unparserContext.ts

@@ -0,0 +1,127 @@
+/* eslint-disable prefer-arrow-callback */
+
+import { Unparser, UnparserResult } from "./unparser.js";
+import { UnparserOutputCompanion } from "./unparserOutputCompanion.js";
+import { unparserImplementationInvariant } from "./unparserImplementationInvariant.js";
+import { parserImplementationInvariant } from "./parserImplementationInvariant.js";
+
+export type UnparserContext<Sequence, Element> = {
+	get position(): number;
+
+	writeLater(length: number): AsyncIterable<WriteLater<Sequence, Element>, WriteLater<Sequence, Element>>;
+	writeEarlier<Input>(
+		writeLater: WriteLater<Sequence, Element>,
+		unparser: Unparser<Input, Sequence, Element>,
+		input: Input,
+	): AsyncIterable<WriteEarlier<Sequence, Element>, void>;
+};
+
+export class WriteLater<Sequence, Element> extends Error {
+	name = 'WriteLater';
+
+	constructor (
+		private readonly _position: number,
+		private readonly _length: number,
+	) {
+		super(`(position: ${_position}, length: ${_length})`);
+	}
+
+	get position() {
+		return this._position;
+	}
+
+	get positionEnd() {
+		return this._position + this._length;
+	}
+
+	get length() {
+		return this._length;
+	}
+}
+
+export class WriteEarlier<Sequence, Element> {
+	constructor(
+		public readonly writeLater: WriteLater<Sequence, Element>,
+		public readonly unparserResult: UnparserResult<Sequence, Element>,
+		public readonly unparserContext: UnparserContext<Sequence, Element>,
+	) {}
+}
+
+export class UnparserContextImplementation<Sequence, Element> implements UnparserContext<Sequence, Element> {
+	private _position: number;
+
+	constructor(
+		private readonly _outputCompanion: UnparserOutputCompanion<Sequence, Element>,
+		position = 0,
+	) {
+		this._position = position;
+	}
+
+	get position() {
+		return this._position;
+	}
+
+	async * writeLater(length: number): AsyncIterable<WriteLater<Sequence, Element>, WriteLater<Sequence, Element>> {
+		parserImplementationInvariant(
+			length >= 0,
+			'Length of WriteLater must be non-negative, got %s.',
+			length,
+		);
+
+		const writeLater = new WriteLater<Sequence, Element>(this._position, length);
+		yield writeLater;
+		return writeLater;
+	}
+
+	async * writeEarlier<Input>(
+		writeLater: WriteLater<Sequence, Element>,
+		unparser: Unparser<Input, Sequence, Element>,
+		input: Input,
+	): AsyncIterable<WriteEarlier<Sequence, Element>, void> {
+		const unparserContext = new UnparserContextImplementation(this._outputCompanion, writeLater.position);
+		yield new WriteEarlier(
+			writeLater,
+			(async function * () {
+				const startPosition = unparserContext.position;
+
+				yield * unparser(input, unparserContext);
+
+				const endPosition = unparserContext.position;
+				const writtenLength = endPosition - startPosition;
+
+				unparserImplementationInvariant(
+					writtenLength === writeLater.length,
+					[
+						'WriteEarlier was supposed to write %s elements but wrote %s elements instead.',
+						'Corresponding WriteLater stack (this is where it was created): %s',
+						'End of corresponding WriteEarlier stack.',
+					],
+					writeLater.length,
+					writtenLength,
+					writeLater.stack,
+				);
+			})(),
+			unparserContext,
+		);
+	}
+
+	handleYield(
+		value:
+			| Sequence
+			| WriteLater<Sequence, Element>
+			| WriteEarlier<Sequence, Element>
+		,
+	) {
+		if (value instanceof WriteEarlier) {
+			return;
+		}
+
+		if (value instanceof WriteLater) {
+			this._position += value.length;
+			return;
+		}
+
+		const length = this._outputCompanion.length(value);
+		this._position += length;
+	}
+}

package/src/unparserError.ts

@@ -0,0 +1,12 @@
+
+export class UnparserError extends Error {
+	name = 'UnparserError';
+}
+
+export class UnparserImplementationError extends UnparserError {
+	name = 'UnparserImplementationError';
+}
+
+export class UnparserImplementationInvariantError extends UnparserImplementationError {
+	name = 'UnparserImplementationInvariantError';
+}

package/src/unparserImplementationInvariant.ts

@@ -0,0 +1,6 @@
+import { UnparserImplementationInvariantError } from './unparserError.js';
+import { type Falsy, customInvariant, type ValueOrAccessor } from './customInvariant.js';
+
+export function unparserImplementationInvariant<T>(value: T, format: ValueOrAccessor<string | string[]>, ...formatArguments: any[]): Exclude<T, Falsy> {
+	return customInvariant(UnparserImplementationInvariantError, value, format, ...formatArguments);
+}

package/src/unparserOutputCompanion.ts

@@ -0,0 +1,24 @@
+import { StringParserInputCompanion, Uint8ArrayParserInputCompanion } from "./parserInputCompanion.js";
+
+export type UnparserOutputCompanion<Sequence, Element> = {
+	is(value: unknown): value is Sequence;
+	from(elements: Element[]): Sequence;
+	concat(sequences: Sequence[]): Sequence;
+	length(sequence: Sequence): number;
+};
+
+export class StringUnparserOutputCompanion extends StringParserInputCompanion implements UnparserOutputCompanion<string, string> {
+	concat(sequences: string[]): string {
+		return sequences.join('');
+	}
+}
+
+export const stringUnparserOutputCompanion = new StringUnparserOutputCompanion();
+
+export class Uint8ArrayUnparserOutputCompanion extends Uint8ArrayParserInputCompanion implements UnparserOutputCompanion<Uint8Array, number> {
+	concat(sequences: Uint8Array[]): Uint8Array {
+		return Buffer.concat(sequences);
+	}
+}
+
+export const uint8ArrayUnparserOutputCompanion = new Uint8ArrayUnparserOutputCompanion();

package/src/zip.ts

@@ -4,37 +4,25 @@ export type ZipCompression =
 	| 'deflate'
 ;
 
-export type ZipUnixPermissions = {
-	type: 'unix';
-	unixPermissions: number;
+export type ZipEntryAttributes = {
 };
 
-export type ZipDosPermissions = {
-	type: 'dos';
-	dosPermissions: number;
-};
-
-export type ZipPermissions =
-	| ZipUnixPermissions
-	| ZipDosPermissions
-;
-
-export type ZipFileEntry = {
-	type: 'file';
+type ZipEntryCommon = {
 	path: string;
 	date: Date;
 	comment: string;
-	permissions: ZipPermissions;
+	hostSystem: 'unix' | 'dos';
+	attributes: ZipEntryAttributes;
+};
+
+export type ZipFileEntry = ZipEntryCommon & {
+	type: 'file';
 	compression: ZipCompression;
 	content: Uint8Array;
 };
 
-export type ZipDirectoryEntry = {
+export type ZipDirectoryEntry = ZipEntryCommon & {
 	type: 'directory';
-	path: string;
-	date: Date;
-	comment: string;
-	permissions: ZipPermissions;
 };
 
 export type ZipEntry =
@@ -45,4 +33,4 @@ export type ZipEntry =
 export type Zip = {
 	comment: string;
 	entries: ZipEntry[];
-}
+};

package/src/zipParser.test.ts

@@ -1,22 +1,16 @@
 import { testProp } from '@fast-check/ava';
 import { arbitraryZipStream } from './arbitraryZipStream.js';
 import { zipParser } from './zipParser.js';
-import { uint8ArrayInputCompanion } from './inputCompanion.js';
+import { uint8ArrayParserInputCompanion } from './parserInputCompanion.js';
 import { runParser } from './parser.js';
 
-async function * readableStreamToUint8ArrayAsyncIterator(stream: ReadableStream<Uint8Array>) {
-	for await (const chunk of stream) {
-		yield chunk;
-	}
-}
-
 testProp(
 	'zip',
 	[
 		arbitraryZipStream,
 	],
 	async (t, [ zip, zipStream ]) => {
-		const actual = await runParser(zipParser, readableStreamToUint8ArrayAsyncIterator(zipStream), uint8ArrayInputCompanion, {
+		const actual = await runParser(zipParser, zipStream, uint8ArrayParserInputCompanion, {
 			errorJoinMode: 'all',
 		});