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

package/dist/emit/runtime.emitter.js

@@ -227,7 +227,7 @@ export async function askCan(
 				: question,
 		),
 	});
-	const response = await post(connection, "/_access/can", operation, headers, body, options);
+	const response = await post(connection, "/_access/can", operation, headers, body, options.signal);
 	return decoded(operation, response.status, () => {
 		const data: unknown = response.data;
 		if (!Array.isArray(data) || data.length !== questions.length || !data.every((answer) => typeof answer === "boolean")) {
@@ -269,7 +269,8 @@ import {
 } from ${from("./errors")};
 
 /**
- * The transport of Aventara protocol version 1: one POST per operation,
+ * The transport of Aventara protocol version 1: one POST per operation, or one
+ * POST /_all for an Operation Set of them,
  * sent with the protocol version and ClientContract hash, its response
  * read by the protocol's rule: A1xxx resolves with the envelope's data, every other
  * code throws its AvError subclass, and anything that is not a framework
@@ -297,6 +298,9 @@ const FRAMEWORK_HEADERS: Readonly<Record<string, string>> = {
 	[WIRE_PREFIX + ${JSON.stringify(IDENTITY_HEADERS.contractHash)}]: CLIENT_CONTRACT_HASH,
 };
 
+/** The media type of a streamed Operation Set answer: one JSON line per entry. */
+const NDJSON = "application/x-ndjson";
+
 /** The request id header: AvCallOptions.requestId sends it. */
 const REQUEST_ID_HEADER = WIRE_PREFIX + ${JSON.stringify(IDENTITY_HEADERS.requestId)};
 
@@ -307,9 +311,11 @@ export interface StructuralSignal {
 
 /** The request the transport hands to fetch. */
 export interface FetchInit {
-	readonly method: "POST";
+	/** POST, or GET for a cached read. */
+	readonly method: "POST" | "GET";
 	readonly headers: Readonly<Record<string, string>>;
-	readonly body: string;
+	/** The JSON body of a POST; a GET has none. */
+	readonly body?: string;
 	readonly signal?: PlatformSignal;
 }
 
@@ -317,6 +323,16 @@ export interface FetchInit {
 export interface FetchResponse {
 	readonly status: number;
 	text(): Promise<string>;
+	/** Read for an Operation Set's answer: its media type. */
+	readonly headers?: { get(name: string): string | null };
+	/** Read for a streamed Operation Set answer, where the runtime gives one. */
+	readonly body?: { getReader(): BodyReader } | null;
+}
+
+/** What the transport reads of a response body's stream. */
+export interface BodyReader {
+	read(): Promise<{ readonly done: boolean; readonly value?: Uint8Array | undefined }>;
+	cancel(reason?: unknown): Promise<void>;
 }
 
 /** The AvFetch API as far as the transport calls it, where the consumer's lib declares none. */
@@ -346,15 +362,30 @@ export interface TransportConnection {
 
 /** Per-call options. Never serialized into the operation body. */
 export interface AvCallOptions {
-	/** Aborts the request; the call rejects with what fetch rejected with. */
+	/**
+	 * Aborts this call, and only this call. Sent in an Operation Set, the call
+	 * rejects with the signal's reason (an AbortError) and the others go on; sent
+	 * alone, it aborts the request, and the call rejects with what fetch rejected
+	 * with. Aborted before it is sent, it is never sent.
+	 */
 	readonly signal?: PlatformSignal;
-	/** Extra request headers. The framework's own headers cannot be set here. */
+	/**
+	 * Extra request headers. The framework's own headers cannot be set here. A
+	 * call with headers is sent alone, never in an Operation Set.
+	 */
 	readonly headers?: Readonly<Record<string, string>>;
 	/**
 	 * Sent as the request id header (Aventara-Request-Id); the empty string is
-	 * absent. It wins over that header in headers, which it overwrites.
+	 * absent. It wins over that header in headers, which it overwrites. A call
+	 * with a request id is sent alone, never in an Operation Set.
 	 */
 	readonly requestId?: string;
+	/**
+	 * false sends this operation call to its own route, never in an Operation Set
+	 * (POST /_all) with the calls made beside it. A transaction is always
+	 * sent alone.
+	 */
+	readonly grouping?: boolean;
 }
 
 type SuccessCode = Exclude<AvOperationCode, AvOperationErrorCode>;
@@ -405,6 +436,80 @@ export function refuseUnsentValues(
 	);
 }
 
+/** One operation, checked and encoded when it was called: what any request for it sends. */
+export interface PreparedOperation {
+	readonly resource: string;
+	readonly family: string;
+	readonly variant: string;
+	/** How a failure names it: \`"Post" find.many\`. */
+	readonly label: string;
+	/** Its request headers: the framework's, and the caller's when it is sent alone. */
+	readonly headers: Readonly<Record<string, string>>;
+	/** The caller's headers alone (its request id among them): what a cached read's GET sends. */
+	readonly callerHeaders: Readonly<Record<string, string>>;
+	/** Its arguments in wire form, as JSON text: its own route's body. */
+	readonly body: string;
+}
+
+/**
+ * Checks and encodes one operation call, sending nothing: the checks
+ * {@link execute} runs before it sends, in its order, and with its errors.
+ */
+export function prepareOperation(
+	resource: string,
+	family: string,
+	variant: string,
+	args: Readonly<Record<string, unknown>>,
+	options: AvCallOptions = {},
+	check?: (resource: string, family: string, args: unknown) => void,
+): PreparedOperation {
+	refuseUnsentValues(resource, family, variant, args, ["arguments"]);
+	check?.(resource, family, args);
+	const label = JSON.stringify(resource) + " " + family + "." + variant;
+	const callerHeaders = callerHeadersOf(options);
+	const headers = { ...FRAMEWORK_HEADERS, ...callerHeaders };
+	const body = serializeWireBody(encodeArguments(argumentObject(args)));
+	return { resource, family, variant, label, headers, callerHeaders, body };
+}
+
+/**
+ * Sends one prepared operation to its own route and settles its envelope.
+ *
+ * @throws as {@link execute} does once its arguments are checked.
+ */
+export async function sendOperation(
+	connection: TransportConnection,
+	operation: PreparedOperation,
+	signal?: PlatformSignal,
+): Promise<unknown> {
+	const response = await post(connection, routeOf(operation), operation.label, operation.headers, operation.body, signal);
+	return decoded(operation.label, response.status, () => decodeResult(DECODE_TABLE, operation.resource, response.data));
+}
+
+/** An operation's own route: \`/_resources/<resource>/<family>/<variant>\`. */
+export function routeOf(operation: PreparedOperation): string {
+	return "/_resources/" + [operation.resource, operation.family, operation.variant].map(encodeURIComponent).join("/");
+}
+
+/**
+ * Sends one cached read as a GET to its own route with \`query\` (its \`q\` and
+ * \`v\`) and only the caller's headers, and settles its envelope as
+ * {@link sendOperation} does.
+ */
+export async function sendRead(
+	connection: TransportConnection,
+	operation: PreparedOperation,
+	query: string,
+	signal?: PlatformSignal,
+): Promise<unknown> {
+	const init: FetchInit =
+		signal === undefined
+			? { method: "GET", headers: operation.callerHeaders }
+			: { method: "GET", headers: operation.callerHeaders, signal };
+	const response = await received(connection, routeOf(operation) + "?" + query, operation.label, init);
+	return decoded(operation.label, response.status, () => decodeResult(DECODE_TABLE, operation.resource, response.data));
+}
+
 /**
  * Runs one operation: POSTs its arguments and settles its envelope.
  *
@@ -428,14 +533,7 @@ export async function execute(
 	options: AvCallOptions = {},
 	check?: (resource: string, family: string, args: unknown) => void,
 ): Promise<unknown> {
-	refuseUnsentValues(resource, family, variant, args, ["arguments"]);
-	check?.(resource, family, args);
-	const operation = JSON.stringify(resource) + " " + family + "." + variant;
-	const headers = requestHeaders(options);
-	const body = serializeWireBody(encodeArguments(argumentObject(args)));
-	const path = "/_resources/" + [resource, family, variant].map(encodeURIComponent).join("/");
-	const response = await post(connection, path, operation, headers, body, options);
-	return decoded(operation, response.status, () => decodeResult(DECODE_TABLE, resource, response.data));
+	return sendOperation(connection, prepareOperation(resource, family, variant, args, options, check), options.signal);
 }
 
 /**
@@ -455,7 +553,7 @@ export async function executePlan(
 	const operation = "the transaction";
 	const headers = requestHeaders(options);
 	const body = serializeWireBody(plan);
-	const response = await post(connection, "/_transactions", operation, headers, body, options);
+	const response = await post(connection, "/_transactions", operation, headers, body, options.signal);
 	return decoded(operation, response.status, () => {
 		if (!Array.isArray(response.data) || response.data.length !== resources.length) {
 			throw new TypeError("A committed plan's data must hold one result per operation.");
@@ -471,38 +569,279 @@ async function post(
 	operation: string,
 	headers: Readonly<Record<string, string>>,
 	body: string,
-	options: AvCallOptions,
+	signal: PlatformSignal | undefined,
+): Promise<{ readonly status: number; readonly data: unknown }> {
+	const init: FetchInit = signal === undefined ? { method: "POST", headers, body } : { method: "POST", headers, body, signal };
+	return received(connection, path, operation, init);
+}
+
+/** One request and its settled envelope data, still in wire form. */
+async function received(
+	connection: TransportConnection,
+	path: string,
+	operation: string,
+	init: FetchInit,
 ): Promise<{ readonly status: number; readonly data: unknown }> {
+	const signal = init.signal;
+	const response = await send(connection, path, operation, init);
+	let text: string;
+	try {
+		text = await response.text();
+	} catch (error) {
+		if (signal?.aborted === true) {
+			throw error;
+		}
+		throw new AvTransportError(
+			"The response to " + operation + " (HTTP " + response.status + ") could not be read.",
+			response.status,
+		);
+	}
+	return { status: response.status, data: settle(operation, response.status, text) };
+}
+
+/** One request, until its response arrives; a caller's abort rejects with what fetch rejected with. */
+async function send(
+	connection: TransportConnection,
+	path: string,
+	operation: string,
+	init: FetchInit,
+): Promise<FetchResponse> {
 	const url = connection.entrypoint + path;
-	const init: FetchInit =
-		options.signal === undefined
-			? { method: "POST", headers, body }
-			: { method: "POST", headers, body, signal: options.signal };
+	const signal = init.signal;
 
 	// Called unbound: a browser's fetch refuses a this that is not the global.
 	const fetch = connection.fetch as StructuralFetch;
-	let response: FetchResponse;
 	try {
-		response = await fetch(url, init);
+		return await fetch(url, init);
 	} catch (error) {
-		if (options.signal?.aborted === true) {
+		if (signal?.aborted === true) {
 			throw error;
 		}
 		throw new AvTransportError("The request for " + operation + " failed before any response arrived.", null);
 	}
-	let text: string;
+}
+
+/** How one entry of an Operation Set settled: its decoded data, or what its call rejects with. */
+export type EntryOutcome =
+	| { readonly kind: "value"; readonly value: unknown }
+	| { readonly kind: "error"; readonly error: unknown };
+
+/** What an Operation Set request came to: its entries answered, or no /_all on the server (A2002, A2000). */
+export type OperationSetAnswer = "answered" | "absent";
+
+/** How errors name an Operation Set request. */
+const SET_LABEL = "the Operation Set";
+
+/** The key the client gives the entry at \`index\`: an identifier, never the caller's. */
+export function operationSetKey(index: number): string {
+	return "k" + index;
+}
+
+/** One entry of an Operation Set's body, as JSON text, under \`key\`. */
+export function operationSetEntry(key: string, operation: PreparedOperation): string {
+	return (
+		JSON.stringify(key) +
+		':{"resource":' +
+		JSON.stringify(operation.resource) +
+		',"family":' +
+		JSON.stringify(operation.family) +
+		',"variant":' +
+		JSON.stringify(operation.variant) +
+		',"args":' +
+		operation.body +
+		"}"
+	);
+}
+
+/** The JSON text of an Operation Set's body, around its entries' text. */
+export function operationSetBody(entries: readonly string[]): string {
+	return '{"operations":{' + entries.join(",") + "}}";
+}
+
+/**
+ * Sends prepared operations as one Operation Set (\`POST /_all\`), each under a key
+ * the client makes, and hands each entry's outcome to \`answer\` as it arrives: line
+ * by line when the answer is streamed (NDJSON, asked for where the runtime can
+ * stream), all at once from a plain JSON answer. Each entry decodes and fails as
+ * its own route would answer it. A request refused whole answers every entry with
+ * that refusal, except A2002 or A2000, which answer none: the server has no /_all.
+ * A response that is not an Aventara answer answers each entry still waiting with
+ * AvTransportError. Never rejects.
+ */
+export async function sendOperationSet(
+	connection: TransportConnection,
+	operations: readonly PreparedOperation[],
+	signal: PlatformSignal | undefined,
+	answer: (index: number, outcome: EntryOutcome) => void,
+): Promise<OperationSetAnswer> {
+	const keys = new Map(operations.map((_, index) => [operationSetKey(index), index]));
+	const waiting = new Set(keys.values());
+	const settleEntry = (index: number, outcome: EntryOutcome): void => {
+		if (waiting.delete(index)) {
+			answer(index, outcome);
+		}
+	};
+	const failWaiting = (error: unknown): OperationSetAnswer => {
+		for (const index of [...waiting]) {
+			settleEntry(index, { kind: "error", error });
+		}
+		return "answered";
+	};
+	const entryOf = (index: number, status: number, envelope: unknown): EntryOutcome => {
+		const operation = operations[index] as PreparedOperation;
+		try {
+			const data = settleEnvelope(operation.label, status, envelope);
+			return { kind: "value", value: decoded(operation.label, status, () => decodeResult(DECODE_TABLE, operation.resource, data)) };
+		} catch (error) {
+			return { kind: "error", error };
+		}
+	};
+	const streaming = canStream();
+	const headers: Record<string, string> = streaming ? { ...FRAMEWORK_HEADERS, Accept: NDJSON } : { ...FRAMEWORK_HEADERS };
+	const body = operationSetBody(operations.map((operation, index) => operationSetEntry(operationSetKey(index), operation)));
+
+	let response: FetchResponse;
 	try {
-		text = await response.text();
+		response = await send(
+			connection,
+			"/_all",
+			SET_LABEL,
+			signal === undefined ? { method: "POST", headers, body } : { method: "POST", headers, body, signal },
+		);
 	} catch (error) {
-		if (options.signal?.aborted === true) {
-			throw error;
-		}
-		throw new AvTransportError(
-			"The response to " + operation + " (HTTP " + response.status + ") could not be read.",
+		return failWaiting(error);
+	}
+	const unreadable = (): AvTransportError =>
+		new AvTransportError("The response to " + SET_LABEL + " (HTTP " + response.status + ") could not be read.", response.status);
+	const malformed = (): AvTransportError =>
+		new AvTransportError(
+			"The response to " + SET_LABEL + " (HTTP " + response.status + ") is not an Aventara Operation Set answer.",
 			response.status,
 		);
+
+	const mediaType = (response.headers?.get("content-type") ?? "").split(";")[0]?.trim().toLowerCase();
+	if (mediaType !== NDJSON) {
+		let text: string;
+		try {
+			text = await response.text();
+		} catch {
+			return failWaiting(unreadable());
+		}
+		const envelope = envelopeOf(parseJson(text));
+		if (envelope === undefined) {
+			return failWaiting(
+				new AvTransportError(
+					"The response to " + SET_LABEL + " (HTTP " + response.status + ") is not an Aventara response envelope.",
+					response.status,
+				),
+			);
+		}
+		if (envelope.outcome === "failure") {
+			// A server without /_all: A2002 (no such route), or A2000 from a server older
+			// than Operation Sets, which reads /_all as a malformed operation path.
+			return envelope.code === "A2002" || envelope.code === "A2000"
+				? "absent"
+				: failWaiting(frameworkErrorOf(envelope.code, envelope.cause));
+		}
+		const entries = envelope.data;
+		if (!isRecord(entries)) {
+			return failWaiting(malformed());
+		}
+		for (const [key, index] of keys) {
+			if (Object.hasOwn(entries, key)) {
+				settleEntry(index, entryOf(index, response.status, entries[key]));
+			}
+		}
+		return failWaiting(
+			new AvTransportError(
+				"The response to " + SET_LABEL + " (HTTP " + response.status + ") holds no answer for this call.",
+				response.status,
+			),
+		);
 	}
-	return { status: response.status, data: settle(operation, response.status, text) };
+
+	// One line: {"key": …, "envelope": …}. false when it is not one of this request's.
+	const readLine = (line: string): boolean => {
+		if (line.trim() === "") {
+			return true;
+		}
+		const parsed = parseJson(line);
+		if (!isRecord(parsed) || !Object.hasOwn(parsed, "envelope") || typeof parsed["key"] !== "string") {
+			return false;
+		}
+		const index = keys.get(parsed["key"]);
+		if (index === undefined) {
+			return false;
+		}
+		settleEntry(index, entryOf(index, response.status, parsed["envelope"]));
+		return true;
+	};
+	const ended = (): OperationSetAnswer =>
+		failWaiting(
+			new AvTransportError(
+				"The response to " + SET_LABEL + " (HTTP " + response.status + ") ended before it answered this call.",
+				response.status,
+			),
+		);
+
+	const reader = streaming ? response.body?.getReader() : undefined;
+	if (reader === undefined) {
+		let text: string;
+		try {
+			text = await response.text();
+		} catch {
+			return failWaiting(unreadable());
+		}
+		for (const line of text.split("\\n")) {
+			if (!readLine(line)) {
+				return failWaiting(malformed());
+			}
+		}
+		return ended();
+	}
+	const decoder = textDecoder();
+	let buffer = "";
+	for (;;) {
+		let chunk: { readonly done: boolean; readonly value?: Uint8Array | undefined };
+		try {
+			chunk = await reader.read();
+		} catch {
+			return failWaiting(unreadable());
+		}
+		buffer += decoder.decode(chunk.value, { stream: !chunk.done });
+		let newline = buffer.indexOf("\\n");
+		while (newline !== -1) {
+			if (!readLine(buffer.slice(0, newline))) {
+				reader.cancel().catch((): void => undefined);
+				return failWaiting(malformed());
+			}
+			buffer = buffer.slice(newline + 1);
+			newline = buffer.indexOf("\\n");
+		}
+		if (chunk.done) {
+			return readLine(buffer) ? ended() : failWaiting(malformed());
+		}
+	}
+}
+
+/** What the transport reads of a TextDecoder, where the consumer's lib declares none. */
+interface StreamDecoder {
+	decode(input?: Uint8Array, options?: { readonly stream?: boolean }): string;
+}
+
+/** Whether this runtime can read an answer as it streams: a stream reader and a text decoder. */
+function canStream(): boolean {
+	const platform = globalThis as {
+		readonly ReadableStream?: { readonly prototype?: { readonly getReader?: unknown } };
+		readonly TextDecoder?: unknown;
+	};
+	return typeof platform.ReadableStream?.prototype?.getReader === "function" && typeof platform.TextDecoder === "function";
+}
+
+/** The platform's TextDecoder, for UTF-8 (canStream says one exists). */
+function textDecoder(): StreamDecoder {
+	const Platform = (globalThis as unknown as { readonly TextDecoder: new () => StreamDecoder }).TextDecoder;
+	return new Platform();
 }
 
 /**
@@ -529,7 +868,12 @@ function decoded<T>(operation: string, status: number, decode: () => T): T {
  * this client cannot read, which is what AvTransportError means.
  */
 function settle(operation: string, status: number, text: string): unknown {
-	const envelope = envelopeOf(parseJson(text));
+	return settleEnvelope(operation, status, parseJson(text));
+}
+
+/** Settles one parsed response body (or one Operation Set entry's envelope) by the same rule. */
+function settleEnvelope(operation: string, status: number, body: unknown): unknown {
+	const envelope = envelopeOf(body);
 	if (envelope === undefined) {
 		throw new AvTransportError(
 			"The response to " + operation + " (HTTP " + status + ") is not an Aventara response envelope.",
@@ -680,13 +1024,17 @@ function argumentObject(args: unknown): unknown {
 	return args;
 }
 
+/** The framework's headers plus the caller's (see callerHeadersOf). */
+function requestHeaders(options: AvCallOptions): Record<string, string> {
+	return { ...FRAMEWORK_HEADERS, ...callerHeadersOf(options) };
+}
+
 /**
- * The framework's headers plus the caller's, refusing a caller's that names one of
- * the framework's; then requestId, which overwrites any request id header the
- * caller set.
+ * The caller's headers, refusing one that names one of the framework's; then
+ * requestId, which overwrites any request id header the caller set.
  */
-function requestHeaders(options: AvCallOptions): Record<string, string> {
-	const headers: Record<string, string> = { ...FRAMEWORK_HEADERS };
+function callerHeadersOf(options: AvCallOptions): Record<string, string> {
+	const headers: Record<string, string> = {};
 	const owned = new Set(Object.keys(FRAMEWORK_HEADERS).map((name) => name.toLowerCase()));
 	for (const [name, value] of Object.entries(options.headers ?? {})) {
 		if (owned.has(name.toLowerCase())) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aventara/client",
-  "version": "1.0.0-rc.10",
+  "version": "1.0.0-rc.12",
   "license": "SEE LICENSE IN LICENSE",
   "description": "Development-time generator for Aventara typed remote clients.",
   "type": "module",
@@ -28,7 +28,7 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@aventara/core": "1.0.0-rc.10",
+    "@aventara/core": "1.0.0-rc.12",
     "c12": "3.3.4",
     "get-tsconfig": "4.10.0"
   },
@@ -44,7 +44,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@aventara/testing": "1.0.0-rc.10",
+    "@aventara/testing": "1.0.0-rc.12",
     "@types/node": "24.10.1",
     "typescript": "^5.9.2"
   },