@aventara/client 1.0.0-rc.1 → 1.0.0-rc.3

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # @aventara/client
 
+## 1.0.0-rc.3
+
+### Patch Changes
+
+- Updated dependencies [b38034d]
+- Updated dependencies [b38034d]
+- Updated dependencies [b38034d]
+- Updated dependencies [b38034d]
+- Updated dependencies [b38034d]
+- Updated dependencies [b38034d]
+  - @aventara/core@1.0.0-rc.3
+
+## 1.0.0-rc.2
+
+### Patch Changes
+
+- The optional `typescript` peer range is `>=5.7.0` (it was `>=5.5.0`), the lowest TypeScript Aventara's types
+  compile under. `avclient generate` type-checks the client with TypeScript 5.7 or later; under an older one it parses
+  the output with Node's TypeScript parser (`checked: syntax`) and says so in one warning, as it did below 5.5.
+- A generated client sends an `undefined` array element (or a hole) as `null`, as `JSON.stringify` writes it, and its
+  `json` codec leaves out a key holding `undefined` and writes such an element as `null`. A `json` value
+  `{ a: undefined, b: [undefined] }` is sent as `{"b":[null]}`, the value the server stores when an in-process caller
+  passes it. In rc.1 the client refused the array element with a `TypeError` before sending. Regenerate the client.
+- A generated client's `json` values admit a key holding `undefined` in their type, as core's `AvJsonValue` now does,
+  so an object with optional properties can be passed where a `json` value is taken; the key is not sent. In rc.1 it
+  was a compile error. Regenerate the client.
+- A generated client refuses at compile time a filter `mode` or `path` that qualifies no operator: one alone, or one
+  whose only neighbour is a `not` holding operators (`{ mode: "insensitive", not: { contains: "x" } }`). Write it
+  inside the `not`. The server refuses the same filters (`A2004`, `V1001`). Regenerate the client.
+- A generated client types a filter's `mode` by the field: `"default"` always, and `"sensitive"` or `"insensitive"`
+  only where the ClientContract's `filterModes` lists them; any other mode is a compile error. On a `json` field an
+  operator object that names `path` takes the modes `pathFilterModes` lists instead, so on Postgres
+  `where: { meta: { stringContains: "x", mode: "insensitive" } }` is a compile error and
+  `where: { meta: { path: ["label"], stringContains: "x", mode: "insensitive" } }` compiles. `isEmpty` is typed as a boolean, `path` as an array of strings and a `json` field's `string*`
+  operand as a string. The server refuses the same values (`A2004`), so the client adds no runtime check of its own.
+  Regenerate the client: the Contract hash changes.
+- The generated client refuses an `undefined` value in a filter before anything is sent. JSON drops `undefined`, so
+  `avClient.Post.update.many({ where: { id: undefined }, data })` reached the server as `where: {}` and updated every
+  row; the same went for `find`, `count`, `delete` and a transaction step. Now an `undefined` anywhere inside a
+  `where` (`AND`, `OR`, `NOT`, relation filters, operator objects such as `{ equals: undefined }` or
+  `{ isEmpty: undefined }`, `in` lists), a `cursor`, a unique selector, the `where` or `cursor` of a relation in
+  `select` or `include`, or a nested write's selectors (`$connect`, `$disconnect`, `$set`, `$delete`, the `where` of
+  `$update`, `$upsert` and `$connectOrCreate`) throws `AvValidationError` (`A2004`) with a `V1001` issue at the path
+  the server uses (`["arguments", "where", "id"]`, or `["operations", 0, "args", "where", "id"]` with the step's
+  `operation` for a transaction), and no request is made. A `where`, `cursor`, `limit` or `offset` that is itself
+  `undefined` is refused the same way, with the server's code (`V1001`; `V1007` for a unique selector, `V1009` for a
+  cursor), at the top level, in a relation under `select` or `include`, and in a nested write's `where`. Leave the
+  key out to mean no filter. Write data is unchanged: an `undefined` field there is not sent. Regenerate the client
+  to get the check.
+- `avclient generate` in a directory with no config names the extensions it looks for as the docs list them:
+  `no framework.client.ts, .mts, .cts, .js, .mjs or .cjs in <directory>; …`. In rc.1 it read
+  `no framework.client.{js,ts,mjs,cjs,mts,cts} in <directory>`. `avclient --help` and `avclient generate --help` list
+  them in the same order: `framework.client.ts (or .mts, .cts, .js, .mjs, .cjs)`. Which files are read is unchanged.
+- Updated dependencies [9366e16]
+- Updated dependencies [9366e16]
+- Updated dependencies [9366e16]
+- Updated dependencies [9366e16]
+  - @aventara/core@1.0.0-rc.2
+
 ## 1.0.0-rc.1
 
 ### Patch Changes

package/README.md

@@ -96,7 +96,7 @@ A failed run leaves the previous output exactly as it was. The whole tree is wri
 `generateAt`, validated there as one program, and only then moved into place. A run killed part-way is repaired by the
 next run that writes, before it writes anything. A first run that fails removes the directories it created.
 
-The validate step is a real type check when your project has the optional peer `typescript` (5.5 to 6). It is resolved
+The validate step is a real type check when your project has the optional peer `typescript` (5.7 to 6). It is resolved
 from your project, so `npx @aventara/client@rc init` type-checks too, under a consumer's strictest plausible settings
 and with nothing outside the tree resolvable. Without it, or under TypeScript 7 (which has no classic compiler API to
 check with), the check falls back to a parse with Node's own TypeScript parser and says so in one warning. It is never

package/dist/cli/command.parser.d.ts

@@ -1,5 +1,5 @@
-export declare const USAGE = "avclient \u2014 generate a typed Aventara client from a deployed ClientContract.\n\nUsage:\n  avclient generate [--yes]   Read framework.client.ts (or .js, .mjs, .cjs, .mts,\n                              .cts) in the current directory, fetch\n                              <entrypoint>/_contract, and write AvClient.ts and\n                              generated/ into its generateAt directory, its imports\n                              spelled as the project's tsconfig.json says.\n  avclient init [options]     Set up this frontend: write framework.client.ts, the\n                              .env entry, the avclient:generate script and the\n                              @aventara/client devDependency; install; generate.\n      --entrypoint <url>      The server's entrypoint [http://localhost:3000/api].\n      --env-var <NAME>        Read it from this variable [AVENTARA_API_URL].\n      --no-env-var            Write it into framework.client.ts as a literal.\n      --generate-at <dir>     Where the client goes [./src/api].\n      --package-manager <npm|pnpm>   [the lockfile's, else the launching one, else npm]\n      --skip-install          Print the install instead of running it.\n      --skip-generate         Do not generate now.\n      -y, --yes               Accept every default, and replace differing content.\n  avclient --help             Print this and exit 0.\n  avclient <command> --help   Print that command's usage and exit 0.\n  avclient --version, -v      Print this generator's version and exit 0.\n\nOptions:\n  -y, --yes   Overwrite or remove content in AvClient.ts and generated/ that the\n              generator did not produce, without asking. Without it, such content\n              is listed and you are asked; where nobody can answer (stdin is not a\n              terminal, as in CI), the run is refused and nothing is touched.\n\nThe generator owns AvClient.ts and generated/ in generateAt, and nothing else\nthere: your own files beside them are never read, moved or removed. Generated\nfiles are replaced on every run; do not edit them.\n\nBefore framework.client.ts is evaluated, the .env cascade is read from the\ncurrent directory, highest precedence first: the process environment,\n.env.<mode>.local, .env.<mode>, .env.local, .env \u2014 where mode is NODE_ENV, or\n\"development\".\n";
-export declare const GENERATE_USAGE = "Usage: avclient generate [--yes]\n\nRead framework.client.ts (or .js, .mjs, .cjs, .mts, .cts) in the current directory,\nfetch <entrypoint>/_contract, and write AvClient.ts and generated/ into its\ngenerateAt directory, its imports spelled as the project's tsconfig.json says.\n\nOptions:\n  -y, --yes   Overwrite or remove content in AvClient.ts and generated/ that the\n              generator did not produce, without asking. Without it, such content\n              is listed and you are asked; where nobody can answer (stdin is not a\n              terminal, as in CI), the run is refused and nothing is touched.\n\nThe generator owns AvClient.ts and generated/ in generateAt, and nothing else\nthere: your own files beside them are never read, moved or removed.\n\nBefore the config is evaluated, the .env cascade is read from the current\ndirectory, highest precedence first: the process environment, .env.<mode>.local,\n.env.<mode>, .env.local, .env \u2014 where mode is NODE_ENV, or \"development\".\n";
+export declare const USAGE = "avclient \u2014 generate a typed Aventara client from a deployed ClientContract.\n\nUsage:\n  avclient generate [--yes]   Read framework.client.ts (or .mts, .cts, .js, .mjs,\n                              .cjs) in the current directory, fetch\n                              <entrypoint>/_contract, and write AvClient.ts and\n                              generated/ into its generateAt directory, its imports\n                              spelled as the project's tsconfig.json says.\n  avclient init [options]     Set up this frontend: write framework.client.ts, the\n                              .env entry, the avclient:generate script and the\n                              @aventara/client devDependency; install; generate.\n      --entrypoint <url>      The server's entrypoint [http://localhost:3000/api].\n      --env-var <NAME>        Read it from this variable [AVENTARA_API_URL].\n      --no-env-var            Write it into framework.client.ts as a literal.\n      --generate-at <dir>     Where the client goes [./src/api].\n      --package-manager <npm|pnpm>   [the lockfile's, else the launching one, else npm]\n      --skip-install          Print the install instead of running it.\n      --skip-generate         Do not generate now.\n      -y, --yes               Accept every default, and replace differing content.\n  avclient --help             Print this and exit 0.\n  avclient <command> --help   Print that command's usage and exit 0.\n  avclient --version, -v      Print this generator's version and exit 0.\n\nOptions:\n  -y, --yes   Overwrite or remove content in AvClient.ts and generated/ that the\n              generator did not produce, without asking. Without it, such content\n              is listed and you are asked; where nobody can answer (stdin is not a\n              terminal, as in CI), the run is refused and nothing is touched.\n\nThe generator owns AvClient.ts and generated/ in generateAt, and nothing else\nthere: your own files beside them are never read, moved or removed. Generated\nfiles are replaced on every run; do not edit them.\n\nBefore framework.client.ts is evaluated, the .env cascade is read from the\ncurrent directory, highest precedence first: the process environment,\n.env.<mode>.local, .env.<mode>, .env.local, .env \u2014 where mode is NODE_ENV, or\n\"development\".\n";
+export declare const GENERATE_USAGE = "Usage: avclient generate [--yes]\n\nRead framework.client.ts (or .mts, .cts, .js, .mjs, .cjs) in the current directory,\nfetch <entrypoint>/_contract, and write AvClient.ts and generated/ into its\ngenerateAt directory, its imports spelled as the project's tsconfig.json says.\n\nOptions:\n  -y, --yes   Overwrite or remove content in AvClient.ts and generated/ that the\n              generator did not produce, without asking. Without it, such content\n              is listed and you are asked; where nobody can answer (stdin is not a\n              terminal, as in CI), the run is refused and nothing is touched.\n\nThe generator owns AvClient.ts and generated/ in generateAt, and nothing else\nthere: your own files beside them are never read, moved or removed.\n\nBefore the config is evaluated, the .env cascade is read from the current\ndirectory, highest precedence first: the process environment, .env.<mode>.local,\n.env.<mode>, .env.local, .env \u2014 where mode is NODE_ENV, or \"development\".\n";
 export declare const INIT_USAGE = "Usage: avclient init [options]\n\nSet up this frontend: write framework.client.ts, the .env entry, the avclient:generate\nscript and the @aventara/client devDependency; install; generate.\n\nOptions:\n  --entrypoint <url>             The server's entrypoint [http://localhost:3000/api].\n  --env-var <NAME>               Read it from this variable [AVENTARA_API_URL].\n  --no-env-var                   Write it into framework.client.ts as a literal.\n  --generate-at <dir>            Where the client goes [./src/api].\n  --package-manager <npm|pnpm>   [the lockfile's, else the launching one, else npm]\n  --skip-install                 Print the install instead of running it.\n  --skip-generate                Do not generate now.\n  --verbose                      Show the install's output as it runs.\n  -y, --yes                      Accept every default, and replace differing content.\n\nOn a terminal every unanswered question is asked; anywhere else, pass its flag\nor --yes, or the run stops before writing anything.\n";
 export type ClientInitCommand = {
     readonly command: "init";

package/dist/cli/command.parser.js

@@ -2,8 +2,8 @@ import { CLIENT_CONFIG_FILE } from "../config/config.loader.js";
 export const USAGE = `avclient — generate a typed Aventara client from a deployed ClientContract.
 
 Usage:
-  avclient generate [--yes]   Read ${CLIENT_CONFIG_FILE} (or .js, .mjs, .cjs, .mts,
-                              .cts) in the current directory, fetch
+  avclient generate [--yes]   Read ${CLIENT_CONFIG_FILE} (or .mts, .cts, .js, .mjs,
+                              .cjs) in the current directory, fetch
                               <entrypoint>/_contract, and write AvClient.ts and
                               generated/ into its generateAt directory, its imports
                               spelled as the project's tsconfig.json says.
@@ -39,7 +39,7 @@ current directory, highest precedence first: the process environment,
 `;
 export const GENERATE_USAGE = `Usage: avclient generate [--yes]
 
-Read ${CLIENT_CONFIG_FILE} (or .js, .mjs, .cjs, .mts, .cts) in the current directory,
+Read ${CLIENT_CONFIG_FILE} (or .mts, .cts, .js, .mjs, .cjs) in the current directory,
 fetch <entrypoint>/_contract, and write AvClient.ts and generated/ into its
 generateAt directory, its imports spelled as the project's tsconfig.json says.
 

package/dist/config/config.loader.d.ts

@@ -1,6 +1,12 @@
 import type { AvClientConfigInput } from "./client-config.interface.js";
 /** Prisma's `SUPPORTED_EXTENSIONS`, in its order. */
 export declare const CLIENT_CONFIG_FILE_EXTENSIONS: readonly [".js", ".ts", ".mjs", ".cjs", ".mts", ".cts"];
+/**
+ * The same extensions as the docs and `avclient --help` list them, TypeScript
+ * first: the order a sentence to the developer names them in. Lookup keeps
+ * {@link CLIENT_CONFIG_FILE_EXTENSIONS}' order, Prisma's.
+ */
+export declare const CLIENT_CONFIG_FILE_EXTENSIONS_AS_LISTED: readonly [".ts", ".mts", ".cts", ".js", ".mjs", ".cjs"];
 /** The config's name, before its extension. */
 export declare const CLIENT_CONFIG_BASENAME = "framework.client";
 /** The config file `avclient init` writes when the project has none. */

package/dist/config/config.loader.js

@@ -9,6 +9,14 @@ export const CLIENT_CONFIG_FILE_EXTENSIONS = [
     ".mts",
     ".cts",
 ];
+export const CLIENT_CONFIG_FILE_EXTENSIONS_AS_LISTED = [
+    ".ts",
+    ".mts",
+    ".cts",
+    ".js",
+    ".mjs",
+    ".cjs",
+];
 export const CLIENT_CONFIG_BASENAME = "framework.client";
 export const CLIENT_CONFIG_FILE = `${CLIENT_CONFIG_BASENAME}.ts`;
 export function clientConfigFilesIn(directory) {
@@ -27,7 +35,8 @@ export function findClientConfigFile(directory) {
 export async function loadClientConfigFile(directory) {
     const name = findClientConfigFile(directory);
     if (name === undefined) {
-        throw new AvClientConfigError(`no ${CLIENT_CONFIG_BASENAME}.{${CLIENT_CONFIG_FILE_EXTENSIONS.map((extension) => extension.slice(1)).join(",")}} in ${path.resolve(directory)}; create ${CLIENT_CONFIG_FILE} with ` +
+        const [first, ...others] = CLIENT_CONFIG_FILE_EXTENSIONS_AS_LISTED;
+        throw new AvClientConfigError(`no ${CLIENT_CONFIG_BASENAME}${first}, ${others.slice(0, -1).join(", ")} or ${others.at(-1)} in ${path.resolve(directory)}; create ${CLIENT_CONFIG_FILE} with ` +
             "`export default defineClientConfig({ entrypoint, generateAt })` (or run `avclient init`) and run the generator from its directory.");
     }
     const file = path.resolve(directory, name);

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

@@ -134,10 +134,8 @@ export function emitClientSurfaceModule(contract, names, style) {
             "\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\tcheckOperation(resource, family, args);\n" +
-                    "\t\t\t\t\treturn execute(connect(), resource, family, variant, args, callOptions);\n" +
-                    "\t\t\t\t},\n"
+                ? "\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)) {\n" +

package/dist/emit/field-check.emitter.js

@@ -141,6 +141,7 @@ function rulesTableSource(contract) {
 function fieldValidatorsSource(contract, from) {
     return `import type { AvFieldCheck } from ${from("../derivation/contracts/field-check")};
 import type { JsonSchema } from ${from("../derivation/contracts/json-shape")};
+import { RECORD_SITES, writeKeysOf } from ${from("./codec")};
 import { DECODE_TABLE } from ${from("./descriptor")};
 import { type AvCause, type AvValidationIssue, frameworkErrorOf } from ${from("./errors")};
 import {
@@ -456,21 +457,9 @@ function shapedValueIssues(schema: JsonSchema, list: boolean, value: unknown, pa
 
 // ---- field validators, judged as the server judges them after its field pipes ----
 
-/** Where each relation directive holds the records its target writes. */
-const RECORD_SITES: { readonly [directive: string]: readonly (string | undefined)[] } = {
-	$create: [undefined],
-	$connect: [],
-	$connectOrCreate: ["create"],
-	$disconnect: [],
-	$set: [],
-	$update: ["data"],
-	$delete: [],
-	$upsert: ["create", "update"],
-};
-
 /** The top-level data records of a create, update or upsert. */
 function writeRecordPaths(family: string, args: unknown): Path[] {
-	const keys = family === "create" || family === "update" ? ["data"] : family === "upsert" ? ["create", "update"] : [];
+	const keys = writeKeysOf(family);
 	const records: Path[] = [];
 	if (!isPlainRecord(args)) {
 		return records;

package/dist/emit/runtime.emitter.js

@@ -209,7 +209,7 @@ const IDENTITY_HEADERS = (() => {
 })();
 function transportModuleSource(from) {
     return `import { CLIENT_CONTRACT_HASH, PROTOCOL_VERSION } from ${from("../metadata")};
-import { decodeResult, encodeArguments, readArgument, serializeWireBody } from ${from("./codec")};
+import { decodeResult, encodeArguments, readArgument, serializeWireBody, unsentValues } from ${from("./codec")};
 import { DECODE_TABLE } from ${from("./descriptor")};
 import {
 	type AvCause,
@@ -319,12 +319,58 @@ type Envelope =
 	| { readonly outcome: "data"; readonly code: SuccessCode; readonly data: unknown }
 	| { readonly outcome: "failure"; readonly code: AvOperationErrorCode; readonly cause: AvCause };
 
+/** What a refusal of an operation's arguments says. */
+const REFUSAL_MESSAGE = "Operation arguments failed framework validation.";
+
+/** What an undefined value the request would leave out is told. */
+const UNSENT_MESSAGE =
+	"Value must not be undefined: sent as JSON it would be left out, and the request would reach more rows.";
+
+/**
+ * Refuses arguments that hold an undefined value whose leaving out would reach more
+ * rows than the caller wrote (in a filter, a unique selector or a cursor, or a where,
+ * cursor, limit or offset left undefined), before anything is sent: JSON would drop
+ * it. Throws the AvValidationError (A2004) the server answers when it is handed such
+ * a value: one issue at each, with the server's code, its path under \`at\`
+ * (["arguments"] for a call, ["operations", i, "args"] for a plan step, whose index
+ * the cause names).
+ */
+export function refuseUnsentValues(
+	resource: string,
+	family: string,
+	variant: string,
+	args: unknown,
+	at: readonly (string | number)[],
+	operation?: number,
+): void {
+	const unsent = unsentValues(DECODE_TABLE, resource, family, variant, args);
+	if (unsent.length === 0) {
+		return;
+	}
+	const issues: readonly AvValidationIssue[] = Object.freeze(
+		unsent.map(({ path, code }) =>
+			Object.freeze({ path: Object.freeze([...at, ...path]), code, message: UNSENT_MESSAGE }),
+		),
+	);
+	throw frameworkErrorOf(
+		"A2004",
+		Object.freeze(
+			operation === undefined ? { message: REFUSAL_MESSAGE, issues } : { message: REFUSAL_MESSAGE, issues, operation },
+		),
+	);
+}
+
 /**
  * Runs one operation: POSTs its arguments and settles its envelope.
  *
+ * @param check the client's own checks of the arguments, run before anything is sent
+ *   (the ClientContract's field validators, when it has any).
  * @returns the envelope's data when the code is A1xxx; null for A1001.
  * @throws the AvError subclass of any other code; AvTransportError when no
- *   framework envelope arrived; TypeError, before anything is sent, when the
+ *   framework envelope arrived; AvValidationError (A2004), before anything is sent,
+ *   when the arguments hold an undefined value JSON would leave out to widen the
+ *   request (see refuseUnsentValues), or when
+ *   \`check\` refuses the arguments; TypeError, before anything is sent, when the
  *   arguments are not a JSON-safe object or a request header is the framework's.
  *   A caller's abort rejects with what fetch rejected with.
  */
@@ -335,7 +381,10 @@ export async function execute(
 	variant: string,
 	args: Readonly<Record<string, unknown>>,
 	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)));

package/dist/emit/scalar.codec.js

@@ -231,13 +231,18 @@ function copyJson(side: Side, value: unknown, path: Path, ancestors: Set<object>
 	if (Array.isArray(value)) {
 		const items: unknown[] = [];
 		for (let index = 0; index < value.length; index += 1) {
-			items.push(copyJson(side, value[index], [...path, index], ancestors));
+			// An undefined element (or a hole) is null, as JSON writes it (rc.2).
+			const item = value[index];
+			items.push(item === undefined ? null : copyJson(side, item, [...path, index], ancestors));
 		}
 		copy = items;
 	} else {
-		// fromEntries defines each key, so "__proto__" stays an own key.
+		// fromEntries defines each key, so "__proto__" stays an own key. A key holding
+		// undefined is left out, as JSON leaves it out (rc.2).
 		copy = Object.fromEntries(
-			Object.entries(value).map(([key, member]) => [key, copyJson(side, member, [...path, key], ancestors)]),
+			Object.entries(value)
+				.filter(([, member]) => member !== undefined)
+				.map(([key, member]) => [key, copyJson(side, member, [...path, key], ancestors)]),
 		);
 	}
 	ancestors.delete(value);
@@ -271,8 +276,10 @@ function writeWireJson(value: unknown, path: Path, ancestors: Set<object>): stri
 	if (Array.isArray(value)) {
 		const items: string[] = [];
 		for (let index = 0; index < value.length; index += 1) {
-			// An undefined element is refused, not stripped: JSON would make it null.
-			items.push(writeWireJson(value[index], [...path, index], ancestors));
+			// An undefined element (or a hole) is null, as JSON writes it (rc.2): the
+			// server reads the same value from an in-process caller.
+			const item = value[index];
+			items.push(item === undefined ? "null" : writeWireJson(item, [...path, index], ancestors));
 		}
 		text = "[" + items.join(",") + "]";
 	} else {
@@ -310,7 +317,8 @@ export function decodeScalar(scalar: AvBuiltInScalar, wire: unknown): unknown {
 /**
  * The JSON text of a request body whose scalars are already encoded. Every
  * undefined property is stripped, at every depth (an optional property is
- * omitted, never sent), and null is kept as the explicit value it is.
+ * omitted, never sent), an undefined array element is null, as JSON.stringify
+ * writes both, and null is kept as the explicit value it is.
  * Anything else that is not JSON-safe is refused rather than coerced: it means a
  * value escaped its scalar codec.
  */
@@ -347,6 +355,215 @@ export function readArgument<T>(path: Path, read: () => T): T {
 	}
 }
 
+/** Where each relation directive holds the records its target writes; its other members select. */
+export const RECORD_SITES: { readonly [directive: string]: readonly (string | undefined)[] } = {
+	$create: [undefined],
+	$connect: [],
+	$connectOrCreate: ["create"],
+	$disconnect: [],
+	$set: [],
+	$update: ["data"],
+	$delete: [],
+	$upsert: ["create", "update"],
+};
+
+/** The members of an operation's arguments that hold its write records. */
+export function writeKeysOf(family: string): readonly string[] {
+	return family === "create" || family === "update" ? ["data"] : family === "upsert" ? ["create", "update"] : [];
+}
+
+/** The code an unsent value is refused with: the server's for that place. */
+export type UnsentCode = "V1001" | "V1007" | "V1009";
+
+/** One value a request would leave out: where it is, and the server's code for it. */
+export interface UnsentValue {
+	readonly path: Path;
+	readonly code: UnsentCode;
+}
+
+/**
+ * Every undefined value an operation's arguments hold where leaving it out would
+ * reach more rows than the caller wrote, in argument order, each with the code the
+ * server answers it with:
+ *
+ * - inside a filter, a unique selector or a cursor, at any depth: a where (AND, OR,
+ *   NOT, a relation filter, an operator object, an in list), a cursor, the where and
+ *   cursor of a relation that select or include reads, and a nested write's
+ *   selectors (what $connect, $disconnect, $set and $delete name, and the where of
+ *   $update, $upsert and $connectOrCreate) (V1001);
+ * - a where, cursor, limit or offset that is itself undefined, as a call's or a
+ *   relation's argument (V1001; a unique variant's where V1007, a cursor V1009),
+ *   and the where of $update (V1001), $upsert or $connectOrCreate (V1007).
+ *
+ * JSON drops an undefined value, so such a value is never sent. An undefined field
+ * of a write record is not sent, which is what leaving it out means; a projection,
+ * an order or a directive left undefined is left out as well.
+ */
+export function unsentValues(
+	table: DecodeTable,
+	resource: string,
+	family: string,
+	variant: string,
+	args: unknown,
+): UnsentValue[] {
+	const found: UnsentValue[] = [];
+	const ancestors = new Set<object>();
+
+	const listAt = (value: unknown, path: Path): readonly unknown[] | undefined =>
+		typeof value === "object" && value !== null && readArgument(path, () => Array.isArray(value))
+			? (value as readonly unknown[])
+			: undefined;
+	const recordAt = (value: unknown, path: Path): Readonly<Record<string, unknown>> | undefined =>
+		typeof value === "object" && value !== null && readArgument(path, () => !Array.isArray(value) && isPlainRecord(value))
+			? (value as Readonly<Record<string, unknown>>)
+			: undefined;
+
+	// Visits each member of a container in order (each entry of a list, each key of a
+	// record), undefined ones only when asked; a container met again on its own
+	// ancestry is not walked again, and the encoder refuses it.
+	const each = (
+		container: readonly unknown[] | Readonly<Record<string, unknown>>,
+		path: Path,
+		withUndefined: boolean,
+		visit: (key: string | number, value: unknown, at: Path) => void,
+	): void => {
+		if (ancestors.has(container)) {
+			return;
+		}
+		ancestors.add(container);
+		const keys: readonly (string | number)[] = Array.isArray(container)
+			? Array.from({ length: readArgument(path, () => container.length) }, (_, index) => index)
+			: readArgument(path, () => Object.keys(container));
+		for (const key of keys) {
+			const at = [...path, key];
+			const value = readArgument(at, () => (container as Readonly<Record<string | number, unknown>>)[key]);
+			if (withUndefined || value !== undefined) {
+				visit(key, value, at);
+			}
+		}
+		ancestors.delete(container);
+	};
+	// One entry, or each entry of a list.
+	const entries = (value: unknown, path: Path, visit: (entry: unknown, at: Path) => void): void => {
+		const list = listAt(value, path);
+		if (list === undefined) {
+			visit(value, path);
+		} else {
+			each(list, path, true, (_index, entry, at) => visit(entry, at));
+		}
+	};
+
+	const filter = (value: unknown, path: Path): void => {
+		if (value === undefined) {
+			found.push({ path, code: "V1001" });
+			return;
+		}
+		const container = listAt(value, path) ?? recordAt(value, path);
+		if (container !== undefined) {
+			each(container, path, true, (_key, member, at) => filter(member, at));
+		}
+	};
+	// A read's own arguments (a call's, or a relation's under select or include):
+	// its where and cursor are filters, its limit and offset bound what it returns.
+	const read = (key: string | number, value: unknown, at: Path, whereCode: UnsentCode, cursorCode: UnsentCode): void => {
+		if (key === "where" || key === "cursor") {
+			if (value === undefined) {
+				found.push({ path: at, code: key === "where" ? whereCode : cursorCode });
+			} else {
+				filter(value, at);
+			}
+		} else if (key === "limit" || key === "offset") {
+			if (value === undefined) {
+				found.push({ path: at, code: "V1001" });
+			}
+		} else if ((key === "select" || key === "include") && value !== undefined) {
+			projection(value, at);
+		}
+	};
+	const projection = (value: unknown, path: Path): void => {
+		const list = listAt(value, path);
+		if (list === undefined) {
+			return;
+		}
+		each(list, path, false, (_index, entry, at) => {
+			const relations = recordAt(entry, at);
+			if (relations === undefined) {
+				return;
+			}
+			each(relations, at, false, (_relation, nested, nestedAt) => {
+				const args = recordAt(nested, nestedAt);
+				if (args !== undefined) {
+					each(args, nestedAt, true, (key, member, memberAt) => read(key, member, memberAt, "V1001", "V1009"));
+				}
+			});
+		});
+	};
+	const writeRecord = (target: string, value: unknown, path: Path): void => {
+		const record = recordAt(value, path);
+		if (record === undefined) {
+			return;
+		}
+		const fields = Object.hasOwn(table, target) ? table[target] : undefined;
+		each(record, path, false, (key, member, at) => {
+			const decoding = fields !== undefined && Object.hasOwn(fields, key) ? fields[key as string] : undefined;
+			if (typeof decoding === "object") {
+				relationWrite(decoding.relation, member, at);
+			}
+		});
+	};
+	const relationWrite = (target: string, value: unknown, path: Path): void => {
+		const directives = recordAt(value, path);
+		if (directives === undefined) {
+			return;
+		}
+		each(directives, path, false, (directive, operand, at) => {
+			const sites = Object.hasOwn(RECORD_SITES, directive) ? RECORD_SITES[directive as string] : undefined;
+			if (sites === undefined) {
+				return;
+			}
+			if (sites.length === 0) {
+				filter(operand, at);
+				return;
+			}
+			entries(operand, at, (entry, entryAt) => {
+				if (sites.includes(undefined)) {
+					writeRecord(target, entry, entryAt);
+					return;
+				}
+				const parts = recordAt(entry, entryAt);
+				if (parts !== undefined) {
+					each(parts, entryAt, true, (key, member, memberAt) => {
+						if (sites.includes(key as string)) {
+							writeRecord(target, member, memberAt);
+						} else if (member !== undefined) {
+							filter(member, memberAt);
+						} else if (key === "where") {
+							found.push({ path: memberAt, code: directive === "$update" ? "V1001" : "V1007" });
+						}
+					});
+				}
+			});
+		});
+	};
+
+	const root = recordAt(args, []);
+	if (root !== undefined) {
+		const writeKeys = writeKeysOf(family);
+		const whereCode: UnsentCode = variant === "unique" ? "V1007" : "V1001";
+		const cursorCode: UnsentCode = family === "find" && variant === "many" ? "V1009" : "V1001";
+		each(root, [], true, (key, value, at) => {
+			if (writeKeys.includes(key as string)) {
+				if (value !== undefined) {
+					entries(value, at, (entry, entryAt) => writeRecord(resource, entry, entryAt));
+				}
+			} else {
+				read(key, value, at, whereCode, cursorCode);
+			}
+		});
+	}
+	return found;
+}
+
 /** How encodeValue treats an object: a scalar's runtime class, a container, or neither. */
 function objectKind(value: object): "datetime" | "decimal" | "bytes" | "container" | "other" {
 	if (value instanceof Date) {

package/dist/emit/transaction.emitter.js

@@ -212,7 +212,7 @@ function transactionModuleSource(from) {
     return `import { encodeArguments, readArgument, serializeWireBody } from ${from("./codec")};
 import { type AvCause, type AvError, frameworkErrorOf } from ${from("./errors")};
 import { fingerprintOf } from ${from("./fingerprint")};
-import { type AvCallOptions, executePlan, type TransportConnection } from ${from("./transport")};
+import { type AvCallOptions, executePlan, refuseUnsentValues, type TransportConnection } from ${from("./transport")};
 
 /**
  * The deferred transaction builder and runner: \`avClient.tx\` defers an operation
@@ -384,8 +384,11 @@ export type PlanCheck = (
  * generated client, one handle twice (AvValidationError A2004 / V1001 at
  * ["operations", i]: the entry itself); a reference to a handle not in the list (AvValidationError A2007 /
  * V1010 at its \`$ref\`); a handle whose arguments could not be read when it was
- * built (the TypeError naming where); and, when \`check\` is given, a step whose
- * values break a field check (AvValidationError A2004, as the server answers it).
+ * built (the TypeError naming where); a step holding an undefined value JSON would
+ * leave out to widen it (AvValidationError A2004, as refuseUnsentValues states it,
+ * the step named);
+ * and, when \`check\` is given, a step whose values break a field check
+ * (AvValidationError A2004, as the server answers it).
  */
 export async function runTransaction(
 	connection: TransportConnection,
@@ -431,6 +434,7 @@ export async function runTransaction(
 				});
 			}
 		}
+		refuseUnsentValues(record.resource, record.family, record.variant, record.args, ["operations", index, "args"], index);
 	}
 
 	check?.(records);

package/dist/output/output.validator.d.ts

@@ -14,7 +14,7 @@ export type TypeScriptResolver = () => Promise<TypeScriptCompiler | undefined>;
  */
 export declare function typeScriptResolverFor(specifier: string, directory: string): TypeScriptResolver;
 export declare function projectTypeScriptResolver(generateAt: string): TypeScriptResolver;
-export declare const MINIMUM_TYPESCRIPT = "5.5.0";
+export declare const MINIMUM_TYPESCRIPT = "5.7.0";
 /** How deeply the tree was judged. */
 export type OutputCheck = "types" | "syntax" | "shape";
 export interface OutputAccepted {
@@ -45,9 +45,8 @@ export declare const SYNTAX_CHECK_UNAVAILABLE_WARNING: string;
 export declare function typeScriptWithoutCompilerApiWarning(version: string, checked: "syntax" | "shape"): string;
 /**
  * The warning a run carries when the project's `typescript` is older than the
- * peer range: its compiler API lacks options the check sets (`Bundler`
- * resolution, `verbatimModuleSyntax`), so its verdict would not be the one a
- * supported compiler gives.
+ * peer range: Aventara's types are not measured under it, so its verdict
+ * would not be the one a supported compiler gives.
  */
 export declare function typeScriptBelowRangeWarning(version: string, checked: "syntax" | "shape"): string;
 /**

package/dist/output/output.validator.js

@@ -24,7 +24,7 @@ export function typeScriptResolverFor(specifier, directory) {
 export function projectTypeScriptResolver(generateAt) {
     return typeScriptResolverFor("typescript", generateAt);
 }
-export const MINIMUM_TYPESCRIPT = "5.5.0";
+export const MINIMUM_TYPESCRIPT = "5.7.0";
 function meetsMinimum(version) {
     const parts = /^(\d+)\.(\d+)\.(\d+)/.exec(version);
     const minimum = MINIMUM_TYPESCRIPT.split(".").map(Number);
@@ -57,7 +57,7 @@ export const SYNTAX_CHECK_UNAVAILABLE_WARNING = "neither `typescript` nor Node's
 export function typeScriptWithoutCompilerApiWarning(version, checked) {
     return (`the installed \`typescript\` ${version} has no classic compiler API (\`createProgram\`), so the generated ` +
         `output was NOT type-checked${checked === "shape" ? " or parsed — only its shape was" : " — only its shape and syntax were"}. ` +
-        "Your project's own `tsc` checks it when it compiles; a `typescript` 5.5 to 6 restores the generator's own type check.");
+        "Your project's own `tsc` checks it when it compiles; a `typescript` 5.7 to 6 restores the generator's own type check.");
 }
 export function typeScriptBelowRangeWarning(version, checked) {
     return (`the installed \`typescript\` ${version} is older than ${MINIMUM_TYPESCRIPT}, the lowest @aventara/client supports, so the generated ` +

package/package.json

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