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

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # @aventara/client
 
+## 1.0.0-rc.11
+
+### Patch Changes
+
+- 6197c08: `@/aventara/universal`'s calls are the generated client's own calls again. The entry no longer wraps each one in
+  `io().then(call)`, so its own `signal`, `avClient.all`'s `signal` and strict abort, and `avLazy` all reach it, in the
+  browser and on the server. Next's `io()` is now awaited before the request is sent.
+
+  In the browser, the calls made in one tick are still grouped into one `/_all`. On the server, none is grouped: each
+  call has a client of its own with grouping off, and it is sent from the async context of the code that made it. Before,
+  one queue served every request. Calls from two concurrent requests, or a call inside `unstable_cache` and one outside
+  it, could share a flush and run with the first call's headers and `state`.
+
+  `avLazy` no longer keeps one answer for every request on a server:
+
+  - The generated client's `avLazy` keeps its answer in a page. On a server (no `location`) it keeps none, and each await
+    makes the call again.
+  - `@aventara/core`'s `avLazy` keeps none: each await makes the call again.
+  - `@/aventara/universal` now exports its own `avLazy`, which keeps one answer per request inside a React render
+    (React's `cache`, which the entry now imports) and none where React keeps no request.
+
+  Before, an `avLazy` made at module scope handed the first request's answer to every request after it.
+
+  `ready()`'s in-process path now splits a cached read's GET URL into its path and its `?q=&v=` query, with an empty
+  body, so the read reaches its GET route instead of being answered as absent.
+
+- 5ac10f7: The generated client's calls are grouped. A call runs when it is made, like `fetch` (a call never awaited still runs;
+  a transaction too), and `avLazy(() => call)`, exported beside `avClient`, makes one only when it is first awaited. The
+  calls made in one tick go out as one `POST /_all` Operation Set,
+  split at `limits.maxAll`, each resolving or throwing on its own as its streamed (NDJSON) or plain JSON answer arrives; a
+  call made alone keeps its own route. A call with `headers` or a `requestId`, a transaction, and any call made with
+  `grouping: false` (per call, or `new AvClient({ grouping: false })`) is sent alone. A server without `/_all` gets the calls
+  again one by one. A call's `signal` aborts that call only, and is never sent if it aborts first. `avClient.all({ … })`
+  awaits an object of calls: strict by default, or `{ settle: true }` for one settled entry per key, with a `signal` that
+  aborts its calls. `all` joins the client's reserved member names: a Resource named `all` is reached as `allModel`.
+
+  A read the ClientContract marks `cache` (a `cache({ for, maxAge })` stage) is sent as
+  `GET /_resources/<R>/find/<variant>?q=<args>&v=<hash>`, alone and never grouped, with only the caller's own headers: `q`
+  is the arguments' canonical JSON, percent-encoded or deflate-raw and base64url when shorter (plain where there is no
+  `CompressionStream`), and a URL longer than 4096 characters is POSTed instead. A client with a cached read carries two
+  more runtime modules, `runtime/cached-read.ts` and `runtime/canonical-json.ts` (core's writer, copied).
+
+- Updated dependencies [6197c08]
+- Updated dependencies [e0e89c1]
+- Updated dependencies [186bc29]
+- Updated dependencies [33b5f83]
+- Updated dependencies [6d8b589]
+- Updated dependencies [11ece49]
+- Updated dependencies [92fd093]
+- Updated dependencies [e5e98e6]
+- Updated dependencies [a05d970]
+  - @aventara/core@1.0.0-rc.11
+
 ## 1.0.0-rc.10
 
 ### Patch Changes

package/README.md

@@ -125,20 +125,112 @@ const maybe = await avClient.User.find.first({ where }); // User | null — a mi
   ClientContract (tests, SSR), and `fetch` is for a custom fetch.
 - The client has one property per Resource, one per family under it, and one per advertised variant. Only what the
   ClientContract advertises exists, in the type and at runtime. A Resource named like one of the client's own members
-  (`tx`, `transaction`, `then`, `constructor`, `Object.prototype`'s names) is reached as `<name>Model`, with one
+  (`all`, `tx`, `transaction`, `then`, `constructor`, `Object.prototype`'s names) is reached as `<name>Model`, with one
   warning; its wire name is unchanged.
 - A call resolves to the data: the record, a list, a count. A first-style miss (`A1001`) is `null`. Every other
   outcome throws the `AvError` subclass of its code (`AvNotFoundError` for a strict-unique miss,
   `AvContractMismatchError` for a stale client, …), or `AvTransportError` when no framework answer arrived.
 - Values are application values: `bigint`, `Date`, `Uint8Array`, the client's `AvDecimal`, JSON values as they are.
   Arguments are encoded and results revived for you; a value that cannot be read throws `AvTransportError`.
-- Per-call options (`AvCallOptions`) are never sent in the body: `signal` (an abort rejects with what `fetch` rejected
-  with), `headers` (the framework's own identity headers are refused), and `requestId`, sent as `Aventara-Request-Id`
-  and winning over that header in `headers`.
+- Per-call options (`AvCallOptions`) are never sent in the body: `signal` (aborts this call only, see below),
+  `headers` (the framework's own identity headers are refused), `requestId`, sent as `Aventara-Request-Id` and winning
+  over that header in `headers`, and `grouping: false` (see below).
 - The named types (`User`, `UserWhere`, `UserUniqueWhere`, `UserOrderBy`, `UserCreateData`, `UserUpdateData`,
   `UserSelect`, `UserInclude`) are named exports, each only when the operation it reads is advertised. A name that would
   clash walks the rename ladder (`User` beside a Resource `UserWhere` becomes `UserModel`), one warning each.
 
+## Calls run when made, together
+
+A call runs when you make it, as `fetch` does: it checks and encodes its arguments and is queued at once, and a call
+you never await still runs. A transaction too. Awaiting a call again does not send it again.
+
+The calls made in one tick go out as one request, `POST /_all` (an Operation Set):
+
+```ts
+const [campaigns, unread, me] = await Promise.all([
+	avClient.Campaign.find.many({ where: { ownerId } }),
+	avClient.Message.find.count({ where: { toId: ownerId, readAt: null } }),
+	avClient.User.find.unique({ where: { id: ownerId } }),
+]); // one request
+```
+
+- Each call runs on the server exactly as it would alone (validation, exposure, policy, limits, pipelines), concurrently
+  with the others and not atomically: a write that ran stays written whatever the others answered. Each call resolves
+  or throws on its own, as soon as its own answer arrives (the client asks for a streamed answer,
+  `Accept: application/x-ndjson`, where the runtime can read one, and reads a plain JSON answer otherwise, as on React
+  Native).
+- Together means made before the microtask queue settles: one `Promise.all`, several async functions run together,
+  `avClient.all`. No timer is involved, and a call made on its own goes to its own route as before.
+- A group larger than the ClientContract's `limits.maxAll` (or `limits.maxRequestBytes`) is split into several
+  requests.
+- Sent alone, never grouped: a call with `headers` or a `requestId` (they belong to one request), a call made with
+  `{ grouping: false }`, every call of a client made with `new AvClient({ grouping: false })`, and a transaction.
+- A server without `/_all` (it answers `A2002`) gets the calls again one by one, and that client stops grouping.
+
+### Aborting a call
+
+A call's `signal` aborts that call and nothing else. Aborted before it is sent, it is never sent. Aborted while its
+group is in flight, it rejects at once with the signal's reason (an `AbortError`), and the others in the request go on;
+the request itself is aborted once no call in it still waits for an answer. Sent alone, the abort aborts its request,
+as before. The server still finishes an operation it has already started: there is no way to cancel a database query
+once it runs.
+
+Nothing is aborted for you: there is no default timeout and no abort on navigation. Pass the signal your data library
+gives you (React Query and SWR pass one per query), or your own.
+
+### `avClient.all`
+
+```ts
+const { campaigns, unread } = await avClient.all({
+	campaigns: avClient.Campaign.find.many({ where: { ownerId } }),
+	unread: avClient.Message.find.count({ where: { toId: ownerId, readAt: null } }),
+});
+```
+
+`all` takes an object of calls and resolves one value per key, typed per key. It is strict: the first failure rejects
+it with that call's error and aborts its other calls. That is fail-fast, not atomic: a write that already ran stays
+written. With `{ settle: true }` every key settles on its own, as `{ status: "fulfilled", value }` or
+`{ status: "rejected", reason }`, and `all` never rejects for one key:
+
+```ts
+const panels = await avClient.all({ campaigns, unread }, { settle: true });
+if (panels.unread.status === "rejected") { /* show that panel's error */ }
+```
+
+`{ signal }` aborts every call of that `all`; a call inside it is aborted by its own signal or by the `all`'s. Calls
+grouped beside it but not in it are never touched. The keys are yours and are never sent.
+
+### `avLazy`: describe now, run later
+
+```ts
+import avClient, { avLazy } from "./api/AvClient";
+
+const posts = avLazy(() => avClient.Post.find.many({ where: { published: true } })); // nothing sent yet
+const list = await posts; // sent now (once, in a page)
+```
+
+`avLazy(() => call)` makes the call on its first `then`, `catch` or `finally`, and settles as that call does. In a
+page it makes the call once and keeps the answer. On a server, where one module serves every request, it keeps nothing:
+each await makes the call again. `avClient.all` accepts it as it accepts a call (its `signal` aborts that call too).
+
+## Cached reads are GETs
+
+A read the deployment caches (a `cache({ for, maxAge })` stage on it, which its ClientContract marks) is sent as a GET,
+so the browser, or a CDN when the stage allows one, may keep its answer:
+
+```
+GET <entrypoint>/_resources/Product/find/many?q=<arguments>&v=<ClientContract hash>
+```
+
+- `q` is the arguments' canonical JSON (keys sorted, so the same read is the same URL), percent-encoded, or that JSON
+  deflate-raw'd and base64url'd when that is shorter. Where the runtime has no `CompressionStream` the plain form is sent.
+- A cached read is never grouped into `/_all`: each keeps its own URL, its own cache entry. Your `headers` and
+  `requestId` go with the GET; it sends no header of its own, so a cross-origin read needs no CORS preflight. Its
+  `signal` aborts it as any call's does.
+- A URL longer than 4096 characters (the whole URL) is POSTed to the same route instead, uncached, as are arguments
+  canonical JSON cannot write.
+- The URL holds the arguments, so it lands in server and proxy logs and in browser history.
+
 ## Transactions
 
 When the ClientContract advertises `interactive` transactions, the client has `avClient.tx` and `avClient.transaction`
@@ -170,7 +262,7 @@ Its source field must have the same type as where it is written:
 
 A mismatch is a type error, and the server refuses it before anything runs (`A2007`/`V1011`).
 
-`avClient.tx.…` builds a handle and sends nothing. `avClient.transaction([...])` sends the plan once and resolves one
+`avClient.tx.…` builds a handle and sends nothing. `avClient.transaction([...])` sends the plan once, when made, and resolves one
 result per handle, typed, in order; a failing step throws its error with `cause.operation` naming the step. `$ref` binds
 to the handle's position in the list it runs with. Two mistakes are refused before anything is sent, as core refuses
 them in process: one handle twice (`AvValidationError`, `A2004`/`V1001`), and a `$ref` to a handle not in the list
@@ -244,7 +336,7 @@ repository uses. The `.d.ts` files are core's copied declarations under `generat
 and the named types in `generated/types.d.ts`; the `.ts` sources carry their own types.
 
 - `AvClient.ts`: the entry point you import: `avClient` (the default export), `AvClient`, `AvClientOptions`,
-  `AvCallOptions`, `AvFetch`, `AvOperation`, the named Resource types, the enums, `AvDecimal`, `AvError` and its
+  `AvCallOptions`, `AvFetch`, `AvOperation`, `avLazy`, the named Resource types, the enums, `AvDecimal`, `AvError` and its
   subclasses, `AvTransportError`, and the types `AvCause`, `AvValidationIssue`, `AvOperationCode` and `AvValidationCode`.
 - `generated/client.ts`: the typed client: the class `AvClient`, `AvClientOptions`, `AvCallOptions` and the ready
   instance `avClient`. Every argument and result type is an instantiation of core's own derivation.
@@ -255,6 +347,10 @@ and the named types in `generated/types.d.ts`; the `.ts` sources carry their own
 - `generated/enums.ts`: each enum as a union type and a same-named `as const` object.
 - `generated/metadata.ts`: the ClientContract hash and protocol version the client is bound to, and the entrypoint it
   was generated from, which is its default deployment (an entrypoint carrying credentials is refused at resolution).
+- `generated/runtime/cached-read.ts`: a cached read's GET: its `q` (canonical JSON, plain or deflate-raw), its
+  `v`, and the POST past 4096 characters. Emitted only when the ClientContract caches a read.
+- `generated/runtime/canonical-json.ts`: `@aventara/core`'s canonical JSON writer, its compiled source copied as it is
+  (unchecked: `// @ts-nocheck`). Emitted only when the ClientContract caches a read.
 - `generated/runtime/codec.ts`: the nine scalars' wire codecs, and the request-body serializer.
 - `generated/runtime/decimal.ts`: the framework's `AvDecimal`, with a constructor, `toString` and `toJSON`.
 - `generated/runtime/descriptor.ts`: what the runtime reads of the contract: the result fields it revives and the
@@ -271,12 +367,16 @@ and the named types in `generated/types.d.ts`; the `.ts` sources carry their own
   carries a check.
 - `generated/runtime/fingerprint.ts`: the operation fingerprint (RFC 8785 canonical JSON, SHA-256, base64url),
   dependency-free and pinned to core's. Emitted only when transactions are `interactive`.
+- `generated/runtime/operation-set.ts`: the calls, queued when made, the grouping of the calls made together into
+  Operation Sets
+  (`POST /_all`), per-call abort, and `avClient.all`.
 - `generated/runtime/transaction.ts`: `avClient.tx`'s deferred handles and `avClient.transaction`'s plan assembly,
   refusals and one POST to `/_transactions`. Emitted only when transactions are `interactive`.
-- `generated/runtime/transport.ts`: one POST per operation with the identity headers, and the response read by the
-  protocol's rule. Arguments are encoded by value, results revived by the decode table, and the platform's own `fetch`
-  type is accepted. Its `execute` primitive is module-private: no public file re-exports it, and `AvClient`'s methods
-  wrap it.
+- `generated/runtime/transport.ts`: one POST per operation, or one `POST /_all` per Operation Set (its answer read
+  streamed or whole), with the identity headers, and the response read by the protocol's rule. Arguments are encoded
+  by value, results revived by the decode table, and the platform's own `fetch` type is accepted. Its primitives are
+  module-private: no public file re-exports them, and `AvClient`'s methods reach them through
+  `generated/runtime/operation-set.ts`.
 - `generated/types.d.ts`: the named Resource types, as a declaration file (`User`, `UserWhere`, `UserUniqueWhere`,
   `UserOrderBy`, `UserCreateData`, `UserUpdateData`, `UserSelect`, `UserInclude`), each only when its operation is
   advertised.

package/dist/emit/cached-read.emitter.d.ts

@@ -0,0 +1,3 @@
+import type { EmittedModule } from "./emitted-tree.interface.js";
+import { type ClientModuleStyle } from "./module-style.interface.js";
+export declare function emitCachedReadModules(style: ClientModuleStyle): readonly EmittedModule[];

package/dist/emit/cached-read.emitter.js

@@ -0,0 +1,158 @@
+import { canonicalJson } from "@aventara/core/internal";
+import { moduleSpecifierWriter, } from "./module-style.interface.js";
+export function emitCachedReadModules(style) {
+    return [
+        { path: "runtime/canonical-json.ts", source: CANONICAL_JSON_MODULE },
+        {
+            path: "runtime/cached-read.ts",
+            source: cachedReadModuleSource(moduleSpecifierWriter(style)),
+        },
+    ];
+}
+const MAX_READ_URL_LENGTH = 4096;
+const CANONICAL_JSON_MODULE = `// @ts-nocheck
+/**
+ * The canonical JSON (RFC 8785) of a cached read's arguments: @aventara/core's
+ * own writer, its compiled source copied as it is, so one read is one URL.
+ */
+export ${canonicalJson.toString()}
+`;
+function cachedReadModuleSource(from) {
+    return `import { CLIENT_CONTRACT_HASH } from ${from("../metadata")};
+import { canonicalJson as canonicalJsonOf } from ${from("./canonical-json")};
+import { CACHED_READS } from ${from("./descriptor")};
+import {
+	type PlatformSignal,
+	type PreparedOperation,
+	routeOf,
+	sendOperation,
+	sendRead,
+	type TransportConnection,
+} from ${from("./transport")};
+
+/**
+ * Cached reads: a read the ClientContract marks cache is sent as
+ * GET <entrypoint>/_resources/<resource>/find/<variant>?q=<arguments>&v=<hash>,
+ * alone, so a browser or a CDN may keep its answer. q is the arguments'
+ * canonical JSON, percent-encoded, or deflate-raw and base64url when that is
+ * shorter. A URL longer than MAX_READ_URL_LENGTH is POSTed instead.
+ */
+
+/** The longest URL, in characters, a cached read is sent as a GET; a longer one is POSTed. */
+export const MAX_READ_URL_LENGTH = ${MAX_READ_URL_LENGTH};
+
+/** The canonical JSON of a JSON value; throws a TypeError for anything else. */
+const canonicalJson: (value: unknown) => string = canonicalJsonOf;
+
+/** Whether the ClientContract marks this read cache: it is sent as a GET, never grouped. */
+export function isCachedRead(operation: PreparedOperation): boolean {
+	return (
+		operation.family === "find" &&
+		Object.hasOwn(CACHED_READS, operation.resource) &&
+		(CACHED_READS[operation.resource] ?? []).includes(operation.variant)
+	);
+}
+
+/**
+ * Sends one cached read: a GET with its q and v, or a POST to the same route
+ * when its URL would pass MAX_READ_URL_LENGTH or canonical JSON cannot write its
+ * arguments. Settles as every call does.
+ */
+export async function sendCachedRead(
+	connection: TransportConnection,
+	operation: PreparedOperation,
+	signal?: PlatformSignal,
+): Promise<unknown> {
+	let json: string;
+	try {
+		json = canonicalJson(JSON.parse(operation.body));
+	} catch {
+		return sendOperation(connection, operation, signal);
+	}
+	const query = "q=" + (await queryArgument(json)) + "&v=" + encodeURIComponent(CLIENT_CONTRACT_HASH);
+	return (connection.entrypoint + routeOf(operation) + "?" + query).length > MAX_READ_URL_LENGTH
+		? sendOperation(connection, operation, signal)
+		: sendRead(connection, operation, query, signal);
+}
+
+/** q: the JSON percent-encoded, or deflate-raw and base64url when that is shorter. */
+async function queryArgument(json: string): Promise<string> {
+	const plain = encodeURIComponent(json);
+	const compressed = await deflated(json);
+	return compressed !== undefined && compressed.length < plain.length ? compressed : plain;
+}
+
+/** What the client reads of a CompressionStream, where the consumer's lib declares none. */
+interface Compression {
+	readonly writable: {
+		getWriter(): { write(chunk: Uint8Array): Promise<void>; close(): Promise<void> };
+	};
+	readonly readable: {
+		getReader(): { read(): Promise<{ readonly done: boolean; readonly value?: Uint8Array | undefined }> };
+	};
+}
+
+/** The JSON's UTF-8 bytes deflate-raw'd, in base64url; undefined where the runtime cannot. */
+async function deflated(json: string): Promise<string | undefined> {
+	const platform = globalThis as unknown as {
+		readonly CompressionStream?: new (format: string) => Compression;
+		readonly TextEncoder?: new () => { encode(text: string): Uint8Array };
+	};
+	const Stream = platform.CompressionStream;
+	const Encoder = platform.TextEncoder;
+	if (typeof Stream !== "function" || typeof Encoder !== "function") {
+		return undefined;
+	}
+	try {
+		const stream = new Stream("deflate-raw");
+		const writer = stream.writable.getWriter();
+		const written = writer.write(new Encoder().encode(json)).then(() => writer.close());
+		written.catch((): void => undefined);
+		const reader = stream.readable.getReader();
+		const chunks: Uint8Array[] = [];
+		let total = 0;
+		for (;;) {
+			const chunk = await reader.read();
+			if (chunk.done) {
+				break;
+			}
+			if (chunk.value !== undefined) {
+				chunks.push(chunk.value);
+				total += chunk.value.length;
+			}
+		}
+		await written;
+		const bytes = new Uint8Array(total);
+		let offset = 0;
+		for (const chunk of chunks) {
+			bytes.set(chunk, offset);
+			offset += chunk.length;
+		}
+		return base64Url(bytes);
+	} catch {
+		return undefined;
+	}
+}
+
+const BASE64URL = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+
+/** Base64url without padding. */
+function base64Url(bytes: Uint8Array): string {
+	let text = "";
+	for (let index = 0; index < bytes.length; index += 3) {
+		const first = bytes[index] ?? 0;
+		const second = bytes[index + 1];
+		const third = bytes[index + 2];
+		const group = (first << 16) | ((second ?? 0) << 8) | (third ?? 0);
+		text += BASE64URL.charAt((group >> 18) & 63) + BASE64URL.charAt((group >> 12) & 63);
+		if (second !== undefined) {
+			text += BASE64URL.charAt((group >> 6) & 63);
+		}
+		if (third !== undefined) {
+			text += BASE64URL.charAt(group & 63);
+		}
+	}
+	return text;
+}
+`;
+}

package/dist/emit/client-surface.emitter.js

@@ -49,7 +49,7 @@ export function emitClientSurfaceModule(contract, names, style) {
             "\t\tAccessQuestion,\n" +
             `\t\t${verbs.includes("me") ? "AvAccessMe" : "never"},\n` +
             `\t\t{ ${argsMembers} },\n` +
-            "\t\tAvCallOptions\n" +
+            '\t\tOmit<AvCallOptions, "grouping">\n' +
             "\t>,\n" +
             `\t${["can", ...verbs].map((name) => JSON.stringify(name)).join(" | ")}\n` +
             ">;\n";
@@ -107,12 +107,13 @@ export function emitClientSurfaceModule(contract, names, style) {
             (checked
                 ? `import { ${interactive ? "checkOperation, checkPlan" : "checkOperation"} } from ${from("./runtime/field-validators")};\n`
                 : "") +
+            `import { all, CallQueue${interactive ? ", withSignal" : ""} } from ${from("./runtime/operation-set")};\n` +
             (interactive
                 ? `import { deferOperation, runTransaction } from ${from("./runtime/transaction")};\n`
                 : "") +
             (access === undefined
-                ? `import { type AvCallOptions, execute, type AvFetch, type TransportConnection } from ${from("./runtime/transport")};\n`
-                : `import { askCan, type AvCallOptions, execute, type AvFetch, type TransportConnection } from ${from("./runtime/transport")};\n`) +
+                ? `import type { AvCallOptions, AvFetch, PlatformSignal, TransportConnection } from ${from("./runtime/transport")};\n`
+                : `import { askCan, type AvCallOptions, type AvFetch, type PlatformSignal, type TransportConnection } from ${from("./runtime/transport")};\n`) +
             (verbs.includes("me")
                 ? `import type { AvAccessMe } from ${from("./types")};\n`
                 : "") +
@@ -133,6 +134,11 @@ export function emitClientSurfaceModule(contract, names, style) {
             "\treadonly entrypoint?: string;\n" +
             "\t/** A custom fetch, for authentication or tests; the platform's otherwise. */\n" +
             "\treadonly fetch?: AvFetch;\n" +
+            "\t/**\n" +
+            "\t * false sends every call to its own route. Otherwise the calls made\n" +
+            "\t * together (in one tick) go out as one Operation Set, POST /_all.\n" +
+            "\t */\n" +
+            "\treadonly grouping?: boolean;\n" +
             "}\n" +
             "\n" +
             (shaped === undefined
@@ -166,11 +172,31 @@ export function emitClientSurfaceModule(contract, names, style) {
                     "/** Sends the handles as one plan and resolves their results as a typed tuple. */\n" +
                     "type TransactionCall = <const Steps extends readonly AvOperation<unknown>[]>(\n" +
                     "\tsteps: Steps,\n" +
-                    "\toptions?: AvCallOptions,\n" +
+                    '\toptions?: Omit<AvCallOptions, "grouping">,\n' +
                     ") => Promise<AvTransactionResults<Steps>>;\n"
                 : "") +
             accessTypes +
             "\n" +
+            "/** How one call of `all(…, { settle: true })` settled. */\n" +
+            "type AllSettledEntry<T> =\n" +
+            '\t| { readonly status: "fulfilled"; readonly value: T }\n' +
+            '\t| { readonly status: "rejected"; readonly reason: unknown };\n' +
+            "\n" +
+            "/** Awaits an object of calls together and resolves one value per key, or with `settle: true` one settled entry per key. */\n" +
+            "type AllCall = <E extends { readonly [key: string]: PromiseLike<unknown> }, S extends boolean = false>(\n" +
+            "\tentries: E,\n" +
+            "\toptions?: {\n" +
+            "\t\t/** Aborts every call of this `all`, and no other. */\n" +
+            "\t\treadonly signal?: PlatformSignal;\n" +
+            "\t\t/** true settles every key on its own and never rejects for one; strict otherwise. */\n" +
+            "\t\treadonly settle?: S;\n" +
+            "\t},\n" +
+            ") => Promise<\n" +
+            "\tS extends true\n" +
+            "\t\t? { -readonly [K in keyof E]: AllSettledEntry<Awaited<E[K]>> }\n" +
+            "\t\t: { -readonly [K in keyof E]: Awaited<E[K]> }\n" +
+            ">;\n" +
+            "\n" +
             "/** The generated client: one property per Resource this deployment's ClientContract advertises. */\n" +
             "export interface AvClient extends AvClientSurface {}\n" +
             "\n" +
@@ -188,6 +214,14 @@ export function emitClientSurfaceModule(contract, names, style) {
                     " */\n"
                 : "/** The generated client. */\n") +
             "export class AvClient {\n" +
+            "\t/**\n" +
+            "\t * Awaits an object of calls together, so they go out as one Operation Set,\n" +
+            "\t * and resolves one value per key. Strict: the first failure rejects it and\n" +
+            "\t * aborts its other calls (fail-fast, not atomic: what already ran stays\n" +
+            "\t * done). With `settle: true` every key settles as `{ status, value }` or\n" +
+            "\t * `{ status, reason }`. Its `signal` aborts each of its calls and no other.\n" +
+            "\t */\n" +
+            "\tdeclare readonly all: AllCall;\n" +
             (access === undefined
                 ? ""
                 : "\t/** The policy's answers for the UI (`can`), and the Aventara Access verbs this deployment offers. */\n" +
@@ -204,13 +238,14 @@ export function emitClientSurfaceModule(contract, names, style) {
             '\t\tconst entrypoint = (options.entrypoint ?? DEFAULT_ENTRYPOINT).replace(/\\/+$/, "");\n' +
             "\t\tconst given = options.fetch;\n" +
             "\t\tconst connect = (): TransportConnection => ({ entrypoint, fetch: platformFetch(given) });\n" +
+            "\t\tconst queue = new CallQueue(connect, options.grouping !== false);\n" +
             "\t\tfor (const [resource, families] of operationTree(\n" +
             "\t\t\t(resource, family, variant): OperationMethod =>\n" +
             (checked
-                ? "\t\t\t\tasync (args = {}, callOptions = {}) =>\n" +
-                    "\t\t\t\t\texecute(connect(), resource, family, variant, args, callOptions, checkOperation),\n"
-                : "\t\t\t\tasync (args = {}, callOptions = {}) =>\n" +
-                    "\t\t\t\t\texecute(connect(), resource, family, variant, args, callOptions),\n") +
+                ? "\t\t\t\t(args = {}, callOptions = {}) =>\n" +
+                    "\t\t\t\t\tqueue.operation(resource, family, variant, args, callOptions, checkOperation),\n"
+                : "\t\t\t\t(args = {}, callOptions = {}) =>\n" +
+                    "\t\t\t\t\tqueue.operation(resource, family, variant, args, callOptions),\n") +
             "\t\t)) {\n" +
             "\t\t\tObject.defineProperty(this, propertyOf(resource), { value: families, enumerable: true });\n" +
             "\t\t}\n" +
@@ -225,12 +260,22 @@ export function emitClientSurfaceModule(contract, names, style) {
                     "\t\t}\n" +
                     '\t\tObject.defineProperty(this, "tx", { value: Object.freeze(deferred) });\n' +
                     '\t\tObject.defineProperty(this, "transaction", {\n' +
-                    "\t\t\tvalue: async (steps: unknown, callOptions: AvCallOptions = {}) =>\n" +
+                    "\t\t\tvalue: (steps: unknown, callOptions: AvCallOptions = {}) => {\n" +
+                    "\t\t\t\tconst plan = Array.isArray(steps) ? [...(steps as readonly unknown[])] : steps;\n" +
+                    "\t\t\t\treturn queue.alone(\n" +
+                    "\t\t\t\t\t(signal) =>\n" +
                     (checked
-                        ? "\t\t\t\trunTransaction(connect(), steps, callOptions, checkPlan),\n"
-                        : "\t\t\t\trunTransaction(connect(), steps, callOptions),\n") +
+                        ? "\t\t\t\t\t\trunTransaction(connect(), plan, withSignal(callOptions, signal), checkPlan),\n"
+                        : "\t\t\t\t\t\trunTransaction(connect(), plan, withSignal(callOptions, signal)),\n") +
+                    "\t\t\t\t\tcallOptions.signal,\n" +
+                    "\t\t\t\t);\n" +
+                    "\t\t\t},\n" +
                     "\t\t});\n"
                 : "") +
+            '\t\tObject.defineProperty(this, "all", {\n' +
+            "\t\t\tvalue: (entries: unknown, allOptions?: { readonly signal?: PlatformSignal; readonly settle?: boolean }) =>\n" +
+            "\t\t\t\tall(entries, allOptions),\n" +
+            "\t\t});\n" +
             accessRuntime +
             "\t}\n" +
             "}\n" +

package/dist/emit/client-tree.emitter.js

@@ -1,16 +1,18 @@
 import { AvClientConfigError } from "../config/config.resolver.js";
 import { accessVerbsOf, emitAccessModules } from "./access.emitter.js";
 import { AVCLIENT_REGENERATE, withGeneratedBanner, } from "./banner.emitter.js";
+import { emitCachedReadModules } from "./cached-read.emitter.js";
 import { emitClientSurfaceModule } from "./client-surface.emitter.js";
 import { emitContractCarrierModule } from "./contract-carrier.emitter.js";
 import { ACCESS_DERIVATION_ROOTS, DERIVATION_ROOTS, emitDerivationModules, } from "./derivation.emitter.js";
-import { emitDescriptorModule } from "./descriptor.emitter.js";
+import { contractHasCachedReads, emitDescriptorModule, } from "./descriptor.emitter.js";
 import { CLIENT_ENTRY_FILE, GENERATED_DIRECTORY, } from "./emitted-tree.interface.js";
 import { emitEnumsModule } from "./enum.emitter.js";
 import { emitFieldCheckModules } from "./field-check.emitter.js";
 import { moduleSpecifierWriter, } from "./module-style.interface.js";
 import { deriveEmittedNames } from "./name.deriver.js";
 import { emitNamedTypesModule } from "./named-type.emitter.js";
+import { emitOperationSetModule } from "./operation-set.emitter.js";
 import { emitDecimalModule, emitErrorsModule, emitMetadataModule, emitTransportModule, errorsModuleExports, } from "./runtime.emitter.js";
 import { emitScalarCodecModule } from "./scalar.codec.js";
 import { emitTransactionModules } from "./transaction.emitter.js";
@@ -31,6 +33,8 @@ export function emitClientTree(contract, entrypoint, style, regenerate = AVCLIEN
         emitDecimalModule(),
         emitErrorsModule(regenerate),
         emitTransportModule(style, contract.access !== undefined),
+        emitOperationSetModule(style, contractHasCachedReads(contract)),
+        ...(contractHasCachedReads(contract) ? emitCachedReadModules(style) : []),
         ...emitAccessModules(contract, style),
         emitNamedTypesModule(contract, names, style),
         ...(contract.transactions === "interactive"
@@ -74,6 +78,7 @@ export function clientEntryReExports(style, clientClass = "value", accessVerbs =
         `export type * from ${from("types.d.ts")};\n` +
         `export * from ${from("enums.ts")};\n` +
         `export { AvDecimal } from ${from("runtime/decimal.ts")};\n` +
+        `export { avLazy } from ${from("runtime/operation-set.ts")};\n` +
         `export {\n${errorsModuleExports()
             .map((name) => `\t${name},\n`)
             .join("")}} from ${from("runtime/errors.ts")};\n` +

package/dist/emit/descriptor.emitter.d.ts

@@ -2,3 +2,5 @@ import type { AvContractClient } from "@aventara/core";
 import type { EmittedModule } from "./emitted-tree.interface.js";
 /** `generated/runtime/descriptor.ts`, before the banner. */
 export declare function emitDescriptorModule(contract: AvContractClient): EmittedModule;
+/** Whether the ClientContract marks any read `cache`: a client that sends GETs. */
+export declare function contractHasCachedReads(contract: AvContractClient): boolean;

package/dist/emit/descriptor.emitter.js

@@ -51,9 +51,36 @@ export function emitDescriptorModule(contract) {
             "\tresource: string,\n" +
             "\tfamily: string,\n" +
             "\tvariant: string,\n" +
-            `])[] = [${advertised.length === 0 ? "" : `\n${advertised.join("")}`}];\n`,
+            `])[] = [${advertised.length === 0 ? "" : `\n${advertised.join("")}`}];\n` +
+            "\n" +
+            "/** The ClientContract's limits a group of calls is split by: entries per Operation Set, and request bytes. */\n" +
+            "export const OPERATION_SET_LIMITS: { readonly maxAll: number; readonly maxRequestBytes: number } = {\n" +
+            `\tmaxAll: ${JSON.stringify(contract.limits.maxAll)},\n` +
+            `\tmaxRequestBytes: ${JSON.stringify(contract.limits.maxRequestBytes)},\n` +
+            "};\n" +
+            cachedReadsSource(contract),
     };
 }
+function cachedReadsSource(contract) {
+    const entries = codeUnitOrder(Object.keys(contract.resources)).flatMap((name) => {
+        const variants = codeUnitOrder(Object.keys(contract.resources[name]?.cache ?? {}));
+        return variants.length === 0
+            ? []
+            : [
+                `\t${ownPropertyKey(name)}: [${variants.map((variant) => JSON.stringify(variant)).join(", ")}],\n`,
+            ];
+    });
+    return entries.length === 0
+        ? ""
+        : "\n" +
+            "/** Per Resource, the find variants served as a cached read: sent as a GET. */\n" +
+            "export const CACHED_READS: { readonly [resource: string]: readonly string[] } = {\n" +
+            entries.join("") +
+            "};\n";
+}
+export function contractHasCachedReads(contract) {
+    return Object.values(contract.resources).some((resource) => Object.keys(resource.cache ?? {}).length > 0);
+}
 function decodingOf(field) {
     if (field === undefined) {
         return undefined;

package/dist/emit/emitted-tree.interface.d.ts

@@ -8,7 +8,7 @@ export declare const LEGACY_CLIENT_ENTRY_FILES: readonly string[];
 /** The directory holding every other emitted module, under `generateAt`. */
 export declare const GENERATED_DIRECTORY = "generated";
 export type DerivationModulePath = `derivation/${string}.d.ts`;
-export type GeneratedModulePath = DerivationModulePath | "client.ts" | "contract.ts" | "enums.ts" | "metadata.ts" | "runtime/access.ts" | "runtime/codec.ts" | "runtime/decimal.ts" | "runtime/descriptor.ts" | "runtime/errors.ts" | "runtime/field-check.evaluator.ts" | "runtime/field-validators.ts" | "runtime/fingerprint.ts" | "runtime/transaction.ts" | "runtime/transport.ts" | "types.d.ts";
+export type GeneratedModulePath = DerivationModulePath | "client.ts" | "contract.ts" | "enums.ts" | "metadata.ts" | "runtime/access.ts" | "runtime/cached-read.ts" | "runtime/canonical-json.ts" | "runtime/codec.ts" | "runtime/decimal.ts" | "runtime/descriptor.ts" | "runtime/errors.ts" | "runtime/field-check.evaluator.ts" | "runtime/field-validators.ts" | "runtime/fingerprint.ts" | "runtime/operation-set.ts" | "runtime/transaction.ts" | "runtime/transport.ts" | "types.d.ts";
 export declare const CONTRACT_CARRIER_MODULE = "contract.ts";
 /** A path in the emitted tree: relative to `generateAt`, POSIX-separated. */
 export type EmittedFilePath = typeof CLIENT_ENTRY_FILE | `${typeof GENERATED_DIRECTORY}/${GeneratedModulePath}`;

package/dist/emit/name.deriver.js

@@ -20,6 +20,7 @@ export const RESERVED_EMITTED_NAMES = [
         "AvValidationCode",
         "AvValidationIssue",
         "avClient",
+        "avLazy",
         ...FRAMEWORK_ERROR_CLASS_NAMES,
     ]),
 ].sort();
@@ -54,6 +55,7 @@ export const CLIENT_MEMBER_NAMES = [
     "__lookupGetter__",
     "__lookupSetter__",
     "__proto__",
+    "all",
     "constructor",
     "hasOwnProperty",
     "isPrototypeOf",

package/dist/emit/operation-set.emitter.d.ts

@@ -0,0 +1,3 @@
+import type { EmittedModule } from "./emitted-tree.interface.js";
+import { type ClientModuleStyle } from "./module-style.interface.js";
+export declare function emitOperationSetModule(style: ClientModuleStyle, cached?: boolean): EmittedModule;