@aventara/client 1.0.0-rc.10 → 1.0.0-rc.11

package/dist/emit/operation-set.emitter.js

@@ -0,0 +1,604 @@
+import { moduleSpecifierWriter, } from "./module-style.interface.js";
+export function emitOperationSetModule(style, cached = false) {
+    return {
+        path: "runtime/operation-set.ts",
+        source: operationSetModuleSource(moduleSpecifierWriter(style), cached),
+    };
+}
+function operationSetModuleSource(from, cached) {
+    return `${cached ? `import { isCachedRead, sendCachedRead } from ${from("./cached-read")};\n` : ""}import { OPERATION_SET_LIMITS } from ${from("./descriptor")};
+import {
+	type AvCallOptions,
+	type EntryOutcome,
+	operationSetBody,
+	operationSetEntry,
+	operationSetKey,
+	type PlatformSignal,
+	type PreparedOperation,
+	prepareOperation,
+	sendOperation,
+	sendOperationSet,
+	type TransportConnection,
+} from ${from("./transport")};
+
+/**
+ * The client's calls: sent when made, like fetch, and grouped.
+ *
+ * A call checks and encodes its arguments and is queued when it is made; a call
+ * never awaited still runs. The calls made in one tick go out together as one
+ * Operation Set (POST /_all), each answered on its own as its answer arrives; a
+ * call made alone goes to its own route. avLazy(() => call) makes a call only
+ * when it is first awaited. A call with headers or
+ * a request id, one made with grouping: false, every call of a client made with
+ * grouping: false, and a transaction are always sent alone${cached ? ", and a read the\n * ClientContract marks cache is sent alone as a GET" : ""}.
+ *
+ * A call's signal aborts that call only. Aborted before it is sent, it is never
+ * sent. Nothing is aborted for you: there is no default timeout.
+ */
+
+/** What the queue reads of an AbortSignal, where the consumer's lib declares none. */
+interface AbortSource {
+	readonly aborted: boolean;
+	readonly reason?: unknown;
+	addEventListener?(type: "abort", listener: () => void): void;
+	removeEventListener?(type: "abort", listener: () => void): void;
+}
+
+/** What the queue reads of an AbortController. */
+interface AbortHandle {
+	readonly signal: AbortSource;
+	abort(reason?: unknown): void;
+}
+
+/** How a call is sent. */
+type Dispatch =
+	| { readonly kind: "operation"; readonly operation: PreparedOperation; readonly groupable: boolean }
+	| { readonly kind: "alone"; readonly send: (signal: PlatformSignal | undefined) => Promise<unknown> }
+	| { readonly kind: "refused"; readonly error: unknown };
+
+/** One call: how it is sent, what aborts it, and how it settles. */
+interface CallRecord {
+	readonly dispatch: Dispatch;
+	/** Its own signal, and the signal of each \`all\` it is in. */
+	readonly sources: AbortSource[];
+	/** What an abort of one of its sources does while it waits in the queue or in a set. */
+	onAbort: ((reason: unknown) => void) | undefined;
+	settled: boolean;
+	resolve(value: unknown): void;
+	reject(error: unknown): void;
+}
+
+/** Every call of this tree, by the promise its caller holds. */
+const CALLS = new WeakMap<object, CallRecord>();
+
+/** The platform's AbortController, or undefined where there is none. */
+function abortHandle(): AbortHandle | undefined {
+	const Platform = (globalThis as { readonly AbortController?: new () => AbortHandle }).AbortController;
+	return typeof Platform === "function" ? new Platform() : undefined;
+}
+
+/** What an aborted source rejects with: its reason, else an AbortError. */
+function abortReason(source: AbortSource): unknown {
+	if (source.reason !== undefined) {
+		return source.reason;
+	}
+	const Platform = (globalThis as { readonly DOMException?: new (message: string, name: string) => Error }).DOMException;
+	if (typeof Platform === "function") {
+		return new Platform("This operation was aborted", "AbortError");
+	}
+	const error = new Error("This operation was aborted");
+	error.name = "AbortError";
+	return error;
+}
+
+/** The first of the sources that has aborted. */
+function abortedSource(sources: readonly AbortSource[]): AbortSource | undefined {
+	return sources.find((source) => source.aborted);
+}
+
+/** Each source's listener per record, so it can be removed. */
+const LISTENERS = new WeakMap<AbortSource, Map<CallRecord, () => void>>();
+
+/** Runs \`onAbort\` on the first abort of any of the record's sources, from now on. */
+function watch(record: CallRecord, onAbort: (reason: unknown) => void): void {
+	unwatch(record);
+	record.onAbort = onAbort;
+	for (const source of record.sources) {
+		source.addEventListener?.("abort", aborted(record, source));
+	}
+}
+
+/** Stops watching the record's sources. */
+function unwatch(record: CallRecord): void {
+	if (record.onAbort === undefined) {
+		return;
+	}
+	record.onAbort = undefined;
+	for (const source of record.sources) {
+		const listener = LISTENERS.get(source)?.get(record);
+		if (listener !== undefined) {
+			source.removeEventListener?.("abort", listener);
+			LISTENERS.get(source)?.delete(record);
+		}
+	}
+}
+
+/** The listener a record keeps on one source. */
+function aborted(record: CallRecord, source: AbortSource): () => void {
+	const listeners = LISTENERS.get(source) ?? new Map<CallRecord, () => void>();
+	LISTENERS.set(source, listeners);
+	const listener = (): void => {
+		const onAbort = record.onAbort;
+		unwatch(record);
+		onAbort?.(abortReason(source));
+	};
+	listeners.set(record, listener);
+	return listener;
+}
+
+/** Adds an abort source to a call: one of the \`all\` calls it is in. */
+function addSource(record: CallRecord, source: AbortSource): void {
+	record.sources.push(source);
+	if (record.onAbort !== undefined) {
+		source.addEventListener?.("abort", aborted(record, source));
+	}
+}
+
+/** Settles a call once. */
+function settle(record: CallRecord, outcome: EntryOutcome): void {
+	if (record.settled) {
+		return;
+	}
+	record.settled = true;
+	unwatch(record);
+	if (outcome.kind === "value") {
+		record.resolve(outcome.value);
+	} else {
+		record.reject(outcome.error);
+	}
+}
+
+/**
+ * One signal for the sources: none, the one, or one that aborts with the first
+ * of them (AbortSignal.any, or a controller where the runtime has no any).
+ */
+function signalOf(sources: readonly AbortSource[]): PlatformSignal | undefined {
+	if (sources.length <= 1) {
+		return sources[0] as PlatformSignal | undefined;
+	}
+	const any = (globalThis as unknown as { readonly AbortSignal?: { readonly any?: (signals: readonly AbortSource[]) => AbortSource } })
+		.AbortSignal?.any;
+	if (typeof any === "function") {
+		return any(sources) as unknown as PlatformSignal;
+	}
+	const handle = abortHandle();
+	if (handle === undefined) {
+		return sources[0] as PlatformSignal | undefined;
+	}
+	for (const source of sources) {
+		source.addEventListener?.("abort", () => handle.abort(abortReason(source)));
+	}
+	return handle.signal as unknown as PlatformSignal;
+}
+
+/** The UTF-8 length of a JSON text: what a request body costs against maxRequestBytes. */
+function utf8Length(text: string): number {
+	let bytes = 0;
+	for (let index = 0; index < text.length; index += 1) {
+		const unit = text.charCodeAt(index);
+		if (unit < 0x80) {
+			bytes += 1;
+		} else if (unit < 0x800) {
+			bytes += 2;
+		} else if (unit >= 0xd800 && unit <= 0xdbff && index + 1 < text.length) {
+			bytes += 4;
+			index += 1;
+		} else {
+			bytes += 3;
+		}
+	}
+	return bytes;
+}
+
+/**
+ * A group cut into Operation Sets in submission order: each at most maxAll
+ * entries and at most maxRequestBytes of body. A call too large to share a
+ * request is a set of one, sent to its own route.
+ */
+function split(records: readonly CallRecord[]): CallRecord[][] {
+	const sets: CallRecord[][] = [];
+	let current: CallRecord[] = [];
+	let bytes = utf8Length(operationSetBody([]));
+	for (const record of records) {
+		const operation = (record.dispatch as { readonly operation: PreparedOperation }).operation;
+		const cost = (current.length === 0 ? 0 : 1) + utf8Length(operationSetEntry(operationSetKey(current.length), operation));
+		if (current.length > 0 && (current.length >= OPERATION_SET_LIMITS.maxAll || bytes + cost > OPERATION_SET_LIMITS.maxRequestBytes)) {
+			sets.push(current);
+			current = [];
+			bytes = utf8Length(operationSetBody([]));
+		}
+		bytes += (current.length === 0 ? 0 : 1) + utf8Length(operationSetEntry(operationSetKey(current.length), operation));
+		current.push(record);
+	}
+	if (current.length > 0) {
+		sets.push(current);
+	}
+	return sets;
+}
+
+/**
+ * Whether a call may be sent in an Operation Set: not when the caller opted out,
+ * or set headers or a request id, which belong to one request.
+ */
+function groupable(options: AvCallOptions): boolean {
+	return (
+		options.grouping !== false &&
+		(options.requestId === undefined || options.requestId === "") &&
+		Object.keys(options.headers ?? {}).length === 0
+	);
+}
+
+/**
+ * One client's calls: each queued when it is made, and the ones made in one
+ * tick sent together.
+ */
+export class CallQueue {
+	readonly #connect: () => TransportConnection;
+	#grouping: boolean;
+	#waiting: CallRecord[] = [];
+	#scheduled = false;
+	/** Calls submitted so far: a flush waits until a microtask passes with none. */
+	#submitted = 0;
+
+	constructor(connect: () => TransportConnection, grouping: boolean) {
+		this.#connect = connect;
+		this.#grouping = grouping;
+	}
+
+	/** One operation call: checked, encoded and queued now. */
+	operation(
+		resource: string,
+		family: string,
+		variant: string,
+		args: Readonly<Record<string, unknown>>,
+		options: AvCallOptions,
+		check?: (resource: string, family: string, args: unknown) => void,
+	): Promise<unknown> {
+		let dispatch: Dispatch;
+		try {
+			const operation = prepareOperation(resource, family, variant, args, options, check);
+			dispatch = {
+				kind: "operation",
+				operation,
+				groupable: ${cached ? "!isCachedRead(operation) && " : ""}groupable(options),
+			};
+		} catch (error) {
+			dispatch = { kind: "refused", error };
+		}
+		return this.#call(dispatch, options.signal);
+	}
+
+	/** A call that is always sent alone (a transaction): queued now, \`send\` runs at the flush. */
+	alone(send: (signal: PlatformSignal | undefined) => Promise<unknown>, signal: PlatformSignal | undefined): Promise<unknown> {
+		return this.#call({ kind: "alone", send }, signal);
+	}
+
+	#call(dispatch: Dispatch, signal: PlatformSignal | undefined): Promise<unknown> {
+		let resolve: (value: unknown) => void = () => undefined;
+		let reject: (error: unknown) => void = () => undefined;
+		const settled = new Promise<unknown>((onResolve, onReject) => {
+			resolve = onResolve;
+			reject = onReject;
+		});
+		const record: CallRecord = {
+			dispatch,
+			sources: signal === undefined ? [] : [signal as unknown as AbortSource],
+			onAbort: undefined,
+			settled: false,
+			resolve,
+			reject,
+		};
+		CALLS.set(settled, record);
+		this.#submit(record);
+		return settled;
+	}
+
+	#submit(record: CallRecord): void {
+		const source = abortedSource(record.sources);
+		if (source !== undefined) {
+			settle(record, { kind: "error", error: abortReason(source) });
+			return;
+		}
+		const dispatch = record.dispatch;
+		if (dispatch.kind === "refused") {
+			settle(record, { kind: "error", error: dispatch.error });
+			return;
+		}
+		// Every call waits for the flush, so an all made in the same tick reaches
+		// each of its calls before it is sent, the ones sent alone too.
+		this.#waiting.push(record);
+		this.#submitted += 1;
+		watch(record, (reason) => {
+			this.#waiting = this.#waiting.filter((waiting) => waiting !== record);
+			settle(record, { kind: "error", error: reason });
+		});
+		if (!this.#scheduled) {
+			this.#scheduled = true;
+			this.#settle(-1);
+		}
+	}
+
+	/**
+	 * Flushes once the calls stop coming: a microtask later, and again for as long
+	 * as each microtask brought another call. Awaiting a call adopts it a
+	 * microtask after it is written (Promise.all, an await in an async function), so
+	 * the calls of one Promise.all, and of the async functions it awaits together,
+	 * land in one flush; no timer is involved.
+	 */
+	#settle(seen: number): void {
+		void Promise.resolve().then(() => {
+			if (this.#submitted === seen) {
+				this.#flush();
+			} else {
+				this.#settle(this.#submitted);
+			}
+		});
+	}
+
+	/**
+	 * Sends what waits, in the order it was made: each call that is sent alone to
+	 * its own route; the groupable ones as Operation Sets, a set of one to its own
+	 * route.
+	 */
+	#flush(): void {
+		this.#scheduled = false;
+		const waiting = this.#waiting;
+		this.#waiting = [];
+		const grouped: CallRecord[] = [];
+		for (const record of waiting) {
+			const dispatch = record.dispatch;
+			if (dispatch.kind === "operation" && dispatch.groupable && this.#grouping) {
+				grouped.push(record);
+			} else {
+				this.#sendAlone(record);
+			}
+		}
+		for (const set of split(grouped)) {
+			if (set.length === 1 || !this.#grouping) {
+				for (const record of set) {
+					this.#sendAlone(record);
+				}
+			} else {
+				this.#sendSet(set);
+			}
+		}
+	}
+
+	#sendAlone(record: CallRecord): void {
+		unwatch(record);
+		const source = abortedSource(record.sources);
+		if (source !== undefined) {
+			settle(record, { kind: "error", error: abortReason(source) });
+			return;
+		}
+		const dispatch = record.dispatch;
+		const signal = signalOf(record.sources);
+		let sent: Promise<unknown>;
+		try {
+			sent =
+				dispatch.kind === "operation"
+					? ${cached ? "(isCachedRead(dispatch.operation) ? sendCachedRead : sendOperation)" : "sendOperation"}(this.#connect(), dispatch.operation, signal)
+					: dispatch.kind === "alone"
+						? dispatch.send(signal)
+						: Promise.reject(dispatch.error);
+		} catch (error) {
+			sent = Promise.reject(error);
+		}
+		sent.then(
+			(value) => settle(record, { kind: "value", value }),
+			(error: unknown) => settle(record, { kind: "error", error }),
+		);
+	}
+
+	#sendSet(records: readonly CallRecord[]): void {
+		const waiting = new Set(records);
+		// The request is aborted only when no entry in it still waits for its answer.
+		const request = records.some((record) => record.sources.length > 0) ? abortHandle() : undefined;
+		const answer = (record: CallRecord, outcome: EntryOutcome): void => {
+			if (waiting.delete(record)) {
+				settle(record, outcome);
+			}
+		};
+		for (const record of records) {
+			watch(record, (reason) => {
+				answer(record, { kind: "error", error: reason });
+				if (waiting.size === 0) {
+					request?.abort();
+				}
+			});
+		}
+		let connection: TransportConnection;
+		try {
+			connection = this.#connect();
+		} catch (error) {
+			for (const record of records) {
+				answer(record, { kind: "error", error });
+			}
+			return;
+		}
+		const operations = records.map((record) => (record.dispatch as { readonly operation: PreparedOperation }).operation);
+		void sendOperationSet(connection, operations, request?.signal as PlatformSignal | undefined, (index, outcome) => {
+			const record = records[index];
+			if (record !== undefined) {
+				answer(record, outcome);
+			}
+		}).then((answered) => {
+			if (answered === "absent") {
+				// The server has no /_all: each call again on its own route, and no more sets.
+				this.#grouping = false;
+				for (const record of records) {
+					if (waiting.delete(record)) {
+						this.#sendAlone(record);
+					}
+				}
+			}
+		});
+	}
+}
+
+/** The call's options with \`signal\` in place of its own: what a call sent alone sends with. */
+export function withSignal(options: AvCallOptions, signal: PlatformSignal | undefined): AvCallOptions {
+	const copy: { -readonly [K in keyof AvCallOptions]: AvCallOptions[K] } = { ...options };
+	delete copy.signal;
+	if (signal !== undefined) {
+		copy.signal = signal;
+	}
+	return copy;
+}
+
+/** Each avLazy thenable, by the function that makes its call. */
+const LAZY = new WeakMap<object, () => PromiseLike<unknown>>();
+
+/** Whether this runs in a page (or a worker): it has a location; a server has none. */
+function inPage(): boolean {
+	return (globalThis as { readonly location?: unknown }).location !== undefined;
+}
+
+/**
+ * Describe a call now, make it later: returns a promise-like that calls \`run\`
+ * on its first then, catch or finally, and settles as the call it made. In a
+ * page it makes the call once and keeps its answer. On a server, where one
+ * module serves every request, it keeps nothing: each then, catch or finally
+ * makes the call again, in the context awaiting it. Calls are otherwise made,
+ * queued and sent when written; avClient.all accepts one as it accepts a call,
+ * and its signal aborts that call too.
+ *
+ * @example const posts = avLazy(() => avClient.Post.find.many({}));
+ */
+export function avLazy<T>(run: () => PromiseLike<T>): Promise<T> {
+	let made: Promise<T> | undefined;
+	const make = (): Promise<T> => {
+		if (made !== undefined) {
+			return made;
+		}
+		let call: Promise<T>;
+		try {
+			call = Promise.resolve(run());
+		} catch (error) {
+			call = Promise.reject(error);
+		}
+		if (inPage()) {
+			made = call;
+		}
+		return call;
+	};
+	const lazy = Object.freeze({
+		then: <A = T, B = never>(
+			onFulfilled?: ((value: T) => A | PromiseLike<A>) | null,
+			onRejected?: ((reason: unknown) => B | PromiseLike<B>) | null,
+		): Promise<A | B> => make().then(onFulfilled, onRejected),
+		catch: <B = never>(onRejected?: ((reason: unknown) => B | PromiseLike<B>) | null): Promise<T | B> =>
+			make().catch(onRejected),
+		finally: (onFinally?: (() => void) | null): Promise<T> => make().finally(onFinally),
+		[Symbol.toStringTag]: "Promise",
+	});
+	LAZY.set(lazy, make);
+	return lazy as unknown as Promise<T>;
+}
+
+/** How one call of \`all(…, { settle: true })\` settled. */
+type SettledEntry =
+	| { readonly status: "fulfilled"; readonly value: unknown }
+	| { readonly status: "rejected"; readonly reason: unknown };
+
+function isThenable(value: unknown): value is PromiseLike<unknown> {
+	return (
+		(typeof value === "object" || typeof value === "function") &&
+		value !== null &&
+		typeof (value as { readonly then?: unknown }).then === "function"
+	);
+}
+
+/**
+ * \`avClient.all(entries, options?)\`: awaits an object of calls together, so they
+ * are grouped, and resolves one value per key. Strict by default: the first
+ * failure rejects it, and its other calls are aborted (fail-fast, not atomic:
+ * what already ran stays done). With settle: true, every key settles on its own,
+ * as { status: "fulfilled", value } or { status: "rejected", reason }, and it never
+ * rejects for one key. Its signal aborts each of its calls; inside it a call
+ * waits on its own signal and that one. Calls outside it are never touched. A
+ * promise that is not one of this client's calls is awaited as Promise.all would.
+ *
+ * @throws TypeError, before anything is sent, when entries is not an object
+ *   whose every value is a call.
+ */
+export function all(entries: unknown, options: { readonly signal?: PlatformSignal; readonly settle?: boolean } = {}): Promise<unknown> {
+	if (typeof entries !== "object" || entries === null || Array.isArray(entries)) {
+		return Promise.reject(new TypeError("all takes an object of calls: { key: avClient.Resource.find.many(…), … }."));
+	}
+	const keyed: (readonly [string, PromiseLike<unknown>])[] = [];
+	for (const key of Object.keys(entries)) {
+		const value: unknown = (entries as Readonly<Record<string, unknown>>)[key];
+		if (!isThenable(value)) {
+			return Promise.reject(new TypeError("all's entry " + JSON.stringify(key) + " is not a call."));
+		}
+		keyed.push([key, value]);
+	}
+	// Aborts this all's calls: its signal, or its first failure when strict.
+	const group = abortHandle();
+	const outer = options.signal as AbortSource | undefined;
+	const forward = (): void => {
+		if (outer !== undefined) {
+			group?.abort(abortReason(outer));
+		}
+	};
+	if (outer?.aborted === true) {
+		forward();
+	} else {
+		outer?.addEventListener?.("abort", forward);
+	}
+	// What each of its calls also waits on; without a controller, its signal alone.
+	const source: AbortSource | undefined = group?.signal ?? outer;
+	const outcomes = keyed.map(
+		([, value]) =>
+			new Promise<unknown>((resolve, reject) => {
+				const call = LAZY.get(value)?.() ?? value;
+				const record = CALLS.get(call);
+				if (record !== undefined && source !== undefined) {
+					addSource(record, source);
+				}
+				const signal = group?.signal;
+				if (signal?.aborted === true) {
+					reject(abortReason(signal));
+				} else {
+					signal?.addEventListener?.("abort", () => reject(abortReason(signal)));
+				}
+				call.then(resolve, reject);
+			}),
+	);
+	const done = <T>(result: T): T => {
+		outer?.removeEventListener?.("abort", forward);
+		return result;
+	};
+	const byKey = (values: readonly unknown[]): Readonly<Record<string, unknown>> =>
+		Object.fromEntries(keyed.map(([key], index) => [key, values[index]]));
+	if (options.settle === true) {
+		return Promise.all(
+			outcomes.map((outcome) =>
+				outcome.then(
+					(value): SettledEntry => ({ status: "fulfilled", value }),
+					(reason: unknown): SettledEntry => ({ status: "rejected", reason }),
+				),
+			),
+		).then((settled) => done(byKey(settled)));
+	}
+	return Promise.all(outcomes).then(
+		(values) => done(byKey(values)),
+		(error: unknown) => {
+			group?.abort();
+			throw done(error);
+		},
+	);
+}
+`;
+}