@aventara/client 1.0.0-rc.12 → 1.0.0-rc.13

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

@@ -1,21 +1,77 @@
 import { moduleSpecifierWriter, } from "./module-style.interface.js";
-export function emitOperationSetModule(style, cached = false) {
+export function emitOperationSetModule(style, cached = false, access = false) {
     return {
         path: "runtime/operation-set.ts",
-        source: operationSetModuleSource(moduleSpecifierWriter(style), cached),
+        source: operationSetModuleSource(moduleSpecifierWriter(style), cached) +
+            (access ? ACCESS_CALL_SOURCE : ""),
     };
 }
+const ACCESS_CALL_SOURCE = `
+/** One \`$access\` call, as the hooks see it; only \`can\` sends a request id. */
+export function accessCall(verb: string, options: AvCallOptions): CallIdentity {
+	return identified({ kind: "access", verb, label: "$access." + verb }, verb === "can" ? options.requestId : undefined);
+}
+
+/**
+ * Runs one \`$access\` call under the hooks: onCall (awaited when async, unless
+ * its signal aborts first), then \`run\` with its additions, then onSuccess or
+ * onError. Settles as \`run\` does.
+ */
+export async function observeCall(
+	hooks: CallHooks,
+	call: CallIdentity,
+	signal: PlatformSignal | undefined,
+	run: (additions: CallAdditions) => Promise<unknown>,
+): Promise<unknown> {
+	const additions = startCall(hooks, call);
+	let value: unknown;
+	try {
+		value = await run(additions instanceof Promise ? await untilAborted(additions, signal) : additions);
+	} catch (error) {
+		endCall(hooks, call, { kind: "error", error });
+		throw error;
+	}
+	endCall(hooks, call, { kind: "value", value });
+	return value;
+}
+
+/** An async onCall's additions, or the signal's reason as soon as it aborts first. */
+function untilAborted(additions: Promise<CallAdditions>, signal: PlatformSignal | undefined): Promise<CallAdditions> {
+	const source = signal as unknown as AbortSource | undefined;
+	if (source === undefined) {
+		return additions;
+	}
+	return new Promise<CallAdditions>((resolve, reject) => {
+		const aborted = (): void => reject(abortReason(source));
+		if (source.aborted) {
+			aborted();
+			return;
+		}
+		source.addEventListener?.("abort", aborted);
+		void additions.then((added) => {
+			source.removeEventListener?.("abort", aborted);
+			resolve(added);
+		});
+	});
+}
+`;
+const HOOK_THREW_WARNING = "AVENTARA_CLIENT_HOOK_THREW";
+const HOOK_HEADER_DROPPED_WARNING = "AVENTARA_CLIENT_HOOK_HEADER_DROPPED";
 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 CallAdditions,
 	type EntryOutcome,
+	labelOf,
+	NO_ADDITIONS,
 	operationSetBody,
 	operationSetEntry,
 	operationSetKey,
 	type PlatformSignal,
 	type PreparedOperation,
 	prepareOperation,
+	readAdditions,
 	sendOperation,
 	sendOperationSet,
 	type TransportConnection,
@@ -34,7 +90,193 @@ import {
  *
  * 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.
+ *
+ * The client's hooks see every call: onCall when it is made, and may add to its
+ * request; onSuccess or onError once it settles. Calls whose additions differ
+ * never share an Operation Set.
+ */
+
+/** One call as the hooks see it, frozen: what it is, never its arguments. */
+export type CallIdentity =
+	| {
+			readonly kind: "operation";
+			readonly resource: string;
+			readonly family: string;
+			readonly variant: string;
+			readonly label: string;
+			readonly requestId?: string;
+	  }
+	| { readonly kind: "transaction"; readonly label: string; readonly requestId?: string }
+	| { readonly kind: "access"; readonly verb: string; readonly label: string; readonly requestId?: string };
+
+/**
+ * The client's hooks, as its options hold them. Typed there by the client's own
+ * calls; the queue hands each only the calls this client makes.
+ */
+export interface CallHooks {
+	readonly onCall?: ((call: never) => unknown) | undefined;
+	readonly onSuccess?: ((call: never, result: never) => unknown) | undefined;
+	readonly onError?: ((call: never, error: never) => unknown) | undefined;
+}
+
+/** The call, frozen, with the request id it sends (the empty string is none). */
+function identified(call: CallIdentity, requestId: string | undefined): CallIdentity {
+	if (requestId !== undefined && requestId !== "") {
+		(call as { requestId?: string }).requestId = requestId;
+	}
+	return Object.freeze(call);
+}
+
+/** An operation call, as the hooks see it. */
+function operationCall(resource: string, family: string, variant: string, options: AvCallOptions): CallIdentity {
+	return identified({ kind: "operation", resource, family, variant, label: labelOf(resource, family, variant) }, options.requestId);
+}
+
+/** A transaction, as the hooks see it: one call, whatever its steps. */
+export function transactionCall(options: AvCallOptions): CallIdentity {
+	return identified({ kind: "transaction", label: "the transaction" }, options.requestId);
+}
+
+
+/** What the platform's process offers for a warning, where there is one. */
+type WarningEmitter = (message: string, options: { readonly type: string; readonly code: string }) => void;
+
+/**
+ * Writes one AventaraWarning about a hook, through process.emitWarning where
+ * the runtime has it, else console.warn. Building or writing it never throws.
+ */
+function warnHook(code: string, message: () => string): void {
+	try {
+		const text = message();
+		const platform = globalThis as {
+			readonly process?: { readonly emitWarning?: WarningEmitter };
+			readonly console?: { warn(message: string): void };
+		};
+		const emitWarning = platform.process?.emitWarning;
+		if (typeof emitWarning === "function") {
+			emitWarning(text, { type: "AventaraWarning", code });
+		} else {
+			platform.console?.warn("AventaraWarning: " + text);
+		}
+	} catch {
+		// A warning that cannot be built or written changes nothing.
+	}
+}
+
+/** What a hook threw, as its warning says it. */
+function thrownText(error: unknown): string {
+	try {
+		return error instanceof Error ? String(error.message) : String(error);
+	} catch {
+		return "a value that cannot be written as text";
+	}
+}
+
+/** Reports a hook that threw or rejected, once; the hook is then skipped. */
+function reportHook(hook: keyof CallHooks, call: CallIdentity, error: unknown): void {
+	warnHook(
+		${JSON.stringify(HOOK_THREW_WARNING)},
+		() => "avClient's " + hook + " threw for " + call.label + ", and was skipped: " + thrownText(error),
+	);
+}
+
+/**
+ * Runs one hook, and never throws: a throw is reported and the hook skipped.
+ * A sink's promise is not awaited (its rejection is reported); onCall's
+ * promise comes back as one that never rejects.
  */
+function runHook(hook: keyof CallHooks, hooks: CallHooks, call: CallIdentity, value?: unknown): unknown {
+	try {
+		const run = hooks[hook] as ((call: CallIdentity, value?: unknown) => unknown) | undefined;
+		if (typeof run !== "function") {
+			return undefined;
+		}
+		const returned = hook === "onCall" ? run(call) : run(call, value);
+		if (!isThenable(returned)) {
+			return hook === "onCall" ? returned : undefined;
+		}
+		const awaited = awaitHook(hook, call, returned);
+		return hook === "onCall" ? awaited : undefined;
+	} catch (error) {
+		reportHook(hook, call, error);
+		return undefined;
+	}
+}
+
+/** What a hook's promise resolved to, or undefined, reported, when it rejected. */
+async function awaitHook(hook: keyof CallHooks, call: CallIdentity, returned: PromiseLike<unknown>): Promise<unknown> {
+	try {
+		return await returned;
+	} catch (error) {
+		reportHook(hook, call, error);
+		return undefined;
+	}
+}
+
+/**
+ * onCall's value read as the call's additions; never throws. A header it may
+ * not set is dropped with a warning; a value that cannot be read adds nothing,
+ * reported as a throw.
+ */
+function additionsOf(onCall: object | undefined, call: CallIdentity, value: unknown): CallAdditions {
+	try {
+		return readAdditions(value, (name, reason) => {
+			// Once per header name for each onCall: a page sending the same bad header on every call warns once.
+			const warned = onCall === undefined ? undefined : (DROPPED.get(onCall) ?? new Set<string>());
+			if (warned?.has(name) === true) {
+				return;
+			}
+			if (onCall !== undefined && warned !== undefined) {
+				warned.add(name);
+				DROPPED.set(onCall, warned);
+			}
+			warnHook(
+				${JSON.stringify(HOOK_HEADER_DROPPED_WARNING)},
+				() => "avClient's onCall returned the header " + JSON.stringify(name) + " for " + call.label + ", which " + reason + "; it was dropped.",
+			);
+		});
+	} catch (error) {
+		reportHook("onCall", call, error);
+		return NO_ADDITIONS;
+	}
+}
+
+/** The header names each onCall was warned about dropping. */
+const DROPPED = new WeakMap<object, Set<string>>();
+
+/** The client's onCall, as the key its warnings are kept under; undefined when it has none or it cannot be read. */
+function onCallOf(hooks: CallHooks): object | undefined {
+	try {
+		const onCall: unknown = hooks.onCall;
+		return typeof onCall === "function" ? onCall : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Runs onCall for a call being made: its additions now, or a promise of them
+ * that never rejects when onCall is async. A throw or a rejection adds nothing.
+ */
+function startCall(hooks: CallHooks, call: CallIdentity): CallAdditions | Promise<CallAdditions> {
+	const returned = runHook("onCall", hooks, call);
+	const onCall = onCallOf(hooks);
+	return returned instanceof Promise ? laterAdditions(onCall, call, returned) : additionsOf(onCall, call, returned);
+}
+
+/** An async onCall's additions, once it settles. */
+async function laterAdditions(onCall: object | undefined, call: CallIdentity, returned: Promise<unknown>): Promise<CallAdditions> {
+	return additionsOf(onCall, call, await returned);
+}
+
+/** Runs onSuccess or onError for a call that settled; never throws. */
+function endCall(hooks: CallHooks, call: CallIdentity, outcome: EntryOutcome): void {
+	if (outcome.kind === "value") {
+		runHook("onSuccess", hooks, call, outcome.value);
+	} else {
+		runHook("onError", hooks, call, outcome.error);
+	}
+}
 
 /** What the queue reads of an AbortSignal, where the consumer's lib declares none. */
 interface AbortSource {
@@ -53,12 +295,22 @@ interface AbortHandle {
 /** 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: "alone";
+			readonly send: (connection: TransportConnection, 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;
+	/** The call as the hooks see it, and the hooks that see it. */
+	readonly call: CallIdentity;
+	readonly hooks: CallHooks;
+	/** What onCall added to its request; none until an async onCall resolves. */
+	additions: CallAdditions;
+	/** Whether its async onCall still runs: it is queued once that settles, holding no other call back. */
+	pending: boolean;
 	/** 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. */
@@ -156,6 +408,7 @@ function settle(record: CallRecord, outcome: EntryOutcome): void {
 	} else {
 		record.reject(outcome.error);
 	}
+	endCall(record.hooks, record.call, outcome);
 }
 
 /**
@@ -244,15 +497,17 @@ function groupable(options: AvCallOptions): boolean {
  */
 export class CallQueue {
 	readonly #connect: () => TransportConnection;
+	readonly #hooks: CallHooks;
 	#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) {
+	constructor(connect: () => TransportConnection, grouping: boolean, hooks: CallHooks = {}) {
 		this.#connect = connect;
 		this.#grouping = grouping;
+		this.#hooks = hooks;
 	}
 
 	/** One operation call: checked, encoded and queued now. */
@@ -264,6 +519,8 @@ export class CallQueue {
 		options: AvCallOptions,
 		check?: (resource: string, family: string, args: unknown) => void,
 	): Promise<unknown> {
+		const call = operationCall(resource, family, variant, options);
+		const additions = startCall(this.#hooks, call);
 		let dispatch: Dispatch;
 		try {
 			const operation = prepareOperation(resource, family, variant, args, options, check);
@@ -275,15 +532,28 @@ export class CallQueue {
 		} catch (error) {
 			dispatch = { kind: "refused", error };
 		}
-		return this.#call(dispatch, options.signal);
+		return this.#call(dispatch, options.signal, call, additions);
 	}
 
-	/** 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);
+	/**
+	 * A call that is always sent alone (a transaction): onCall runs now, it is
+	 * queued now, and \`send\` runs at the flush, over the connection that carries
+	 * its additions.
+	 */
+	alone(
+		send: (connection: TransportConnection, signal: PlatformSignal | undefined) => Promise<unknown>,
+		signal: PlatformSignal | undefined,
+		call: CallIdentity,
+	): Promise<unknown> {
+		return this.#call({ kind: "alone", send }, signal, call, startCall(this.#hooks, call));
 	}
 
-	#call(dispatch: Dispatch, signal: PlatformSignal | undefined): Promise<unknown> {
+	#call(
+		dispatch: Dispatch,
+		signal: PlatformSignal | undefined,
+		call: CallIdentity,
+		additions: CallAdditions | Promise<CallAdditions>,
+	): Promise<unknown> {
 		let resolve: (value: unknown) => void = () => undefined;
 		let reject: (error: unknown) => void = () => undefined;
 		const settled = new Promise<unknown>((onResolve, onReject) => {
@@ -292,6 +562,10 @@ export class CallQueue {
 		});
 		const record: CallRecord = {
 			dispatch,
+			call,
+			hooks: this.#hooks,
+			additions: additions instanceof Promise ? NO_ADDITIONS : additions,
+			pending: additions instanceof Promise,
 			sources: signal === undefined ? [] : [signal as unknown as AbortSource],
 			onAbort: undefined,
 			settled: false,
@@ -300,9 +574,29 @@ export class CallQueue {
 		};
 		CALLS.set(settled, record);
 		this.#submit(record);
+		if (additions instanceof Promise) {
+			void this.#whenAdded(record, additions);
+		}
 		return settled;
 	}
 
+	/**
+	 * Queues a call once its async onCall has settled, as a call made then: it
+	 * joins the calls queued with it, and holds back none queued before. A call
+	 * that settled first (an abort) is not queued.
+	 */
+	async #whenAdded(record: CallRecord, additions: Promise<CallAdditions>): Promise<void> {
+		try {
+			record.additions = await additions;
+		} catch {
+			record.additions = NO_ADDITIONS;
+		}
+		record.pending = false;
+		if (!record.settled) {
+			this.#enqueue(record);
+		}
+	}
+
 	#submit(record: CallRecord): void {
 		const source = abortedSource(record.sources);
 		if (source !== undefined) {
@@ -314,14 +608,21 @@ export class CallQueue {
 			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 (!record.pending) {
+			this.#enqueue(record);
+		}
+	}
+
+	/** Queues a call for the next flush. */
+	#enqueue(record: CallRecord): void {
+		// 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;
 		if (!this.#scheduled) {
 			this.#scheduled = true;
 			this.#settle(-1);
@@ -345,35 +646,50 @@ export class CallQueue {
 		});
 	}
 
-	/**
-	 * 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.
-	 */
+	/** Sends what waits: every queued call, none of them waiting on an onCall. */
 	#flush(): void {
 		this.#scheduled = false;
 		const waiting = this.#waiting;
 		this.#waiting = [];
-		const grouped: CallRecord[] = [];
+		this.#dispatch(waiting);
+	}
+
+	/**
+	 * Sends the calls in the order they were made: each call that is sent alone
+	 * to its own route; the groupable ones as Operation Sets of calls whose
+	 * additions are equal, a set of one to its own route.
+	 */
+	#dispatch(waiting: readonly CallRecord[]): void {
+		const groups = new Map<string, CallRecord[]>();
 		for (const record of waiting) {
 			const dispatch = record.dispatch;
 			if (dispatch.kind === "operation" && dispatch.groupable && this.#grouping) {
-				grouped.push(record);
+				const group = groups.get(record.additions.key) ?? [];
+				groups.set(record.additions.key, group);
+				group.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);
+		for (const group of groups.values()) {
+			for (const set of split(group)) {
+				if (set.length === 1 || !this.#grouping) {
+					for (const record of set) {
+						this.#sendAlone(record);
+					}
+				} else {
+					this.#sendSet(set);
 				}
-			} else {
-				this.#sendSet(set);
 			}
 		}
 	}
 
+	/** This client's connection, carrying what onCall added to the request's calls. */
+	#connectWith(additions: CallAdditions): TransportConnection {
+		const connection = this.#connect();
+		return additions.key === "" ? connection : { ...connection, additions };
+	}
+
 	#sendAlone(record: CallRecord): void {
 		unwatch(record);
 		const source = abortedSource(record.sources);
@@ -387,9 +703,9 @@ export class CallQueue {
 		try {
 			sent =
 				dispatch.kind === "operation"
-					? ${cached ? "(isCachedRead(dispatch.operation) ? sendCachedRead : sendOperation)" : "sendOperation"}(this.#connect(), dispatch.operation, signal)
+					? ${cached ? "(isCachedRead(dispatch.operation) ? sendCachedRead : sendOperation)" : "sendOperation"}(this.#connectWith(record.additions), dispatch.operation, signal)
 					: dispatch.kind === "alone"
-						? dispatch.send(signal)
+						? dispatch.send(this.#connectWith(record.additions), signal)
 						: Promise.reject(dispatch.error);
 		} catch (error) {
 			sent = Promise.reject(error);
@@ -419,7 +735,8 @@ export class CallQueue {
 		}
 		let connection: TransportConnection;
 		try {
-			connection = this.#connect();
+			// Every call of a set has the same additions.
+			connection = this.#connectWith(records[0]?.additions ?? NO_ADDITIONS);
 		} catch (error) {
 			for (const record of records) {
 				answer(record, { kind: "error", error });