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

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

@@ -1,3 +1,4 @@
+import { contractHasFieldChecks } from "./field-check.emitter.js";
 import { shapedContractType } from "./json-shape.emitter.js";
 import { importSpecifier, } from "./module-style.interface.js";
 import { ownPropertyKey } from "./name.deriver.js";
@@ -11,6 +12,7 @@ export function emitClientSurfaceModule(contract, names, style) {
             .join("")}R`;
     const resourceKey = renamed.length === 0 ? "R in Resource" : `R in Resource as ${propertyOf}`;
     const interactive = contract.transactions === "interactive";
+    const checked = contractHasFieldChecks(contract);
     const shaped = shapedContractType(contract);
     const C = shaped === undefined ? "ClientContractShape" : "ShapedContract";
     const renamedEntries = renamed.length === 0
@@ -29,38 +31,41 @@ export function emitClientSurfaceModule(contract, names, style) {
             (shaped === undefined
                 ? ""
                 : `import type { JsonFieldType } from ${from("./derivation/contracts/json-shape")};\n`) +
-            `import type { ApplicationScalarForms } from ${from("./derivation/contracts/scalar-value-type")};\n` +
-            `import type { OperationArgumentsFor, ResourceKey } from ${from("./derivation/operations/operation-arguments")};\n` +
-            `import type { ${interactive ? "DeferredOperationCall, " : ""}OperationCall, OperationGrammar } from ${from("./derivation/operations/operation-call")};\n` +
-            `import type { OperationFamily, OperationIdentity } from ${from("./derivation/operations/operation-identity")};\n` +
+            `import type { AvApplicationScalarForms } from ${from("./derivation/contracts/scalar-value-type")};\n` +
+            `import type { AvOperationArgumentsFor, AvResourceKey } from ${from("./derivation/operations/operation-arguments")};\n` +
+            `import type { ${interactive ? "AvDeferredOperationCall, " : ""}AvOperationCall, AvOperationGrammar } from ${from("./derivation/operations/operation-call")};\n` +
+            `import type { AvOperationFamily, AvOperationIdentity } from ${from("./derivation/operations/operation-identity")};\n` +
             `import type { AdmittedOperationResult } from ${from("./derivation/operations/operation-result")};\n` +
             (interactive
-                ? `import type { Operation, TransactionResults } from ${from("./derivation/transactions/deferred-operation")};\n`
+                ? `import type { AvOperation, AvTransactionResults } from ${from("./derivation/transactions/deferred-operation")};\n`
                 : "") +
             `import { DEFAULT_ENTRYPOINT } from ${from("./metadata")};\n` +
-            `import type { Decimal } from ${from("./runtime/decimal")};\n` +
+            `import type { AvDecimal } from ${from("./runtime/decimal")};\n` +
             `import { ADVERTISED_OPERATIONS } from ${from("./runtime/descriptor")};\n` +
+            (checked
+                ? `import { ${interactive ? "checkOperation, checkPlan" : "checkOperation"} } from ${from("./runtime/field-validators")};\n`
+                : "") +
             (interactive
                 ? `import { deferOperation, runTransaction } from ${from("./runtime/transaction")};\n`
                 : "") +
-            `import { type CallOptions, execute, type Fetch, type TransportConnection } from ${from("./runtime/transport")};\n` +
+            `import { type AvCallOptions, execute, type AvFetch, type TransportConnection } from ${from("./runtime/transport")};\n` +
             "\n" +
-            `export type { CallOptions } from ${from("./runtime/transport")};\n` +
+            `export type { AvCallOptions } from ${from("./runtime/transport")};\n` +
             "\n" +
             "/**\n" +
-            " * The forms this client reads and writes: core's application forms —\n" +
-            " * `bigint`, `Date`, `Uint8Array` — with this client's own `Decimal`.\n" +
+            " * The forms this client reads and writes: core's application forms\n" +
+            " * (`bigint`, `Date`, `Uint8Array`) with this client's own `AvDecimal`.\n" +
             " */\n" +
-            'export type ClientScalarForms = Omit<ApplicationScalarForms, "decimal"> & {\n' +
-            "\treadonly decimal: Decimal;\n" +
+            'export type ClientScalarForms = Omit<AvApplicationScalarForms, "decimal"> & {\n' +
+            "\treadonly decimal: AvDecimal;\n" +
             "};\n" +
             "\n" +
             "/** How an `AvClient` reaches its deployment. */\n" +
             "export interface AvClientOptions {\n" +
             "\t/** Another deployment serving exactly the same ClientContract; the generated default otherwise. */\n" +
             "\treadonly entrypoint?: string;\n" +
-            "\t/** A custom fetch — authentication, tests; the platform's otherwise. */\n" +
-            "\treadonly fetch?: Fetch;\n" +
+            "\t/** A custom fetch, for authentication or tests; the platform's otherwise. */\n" +
+            "\treadonly fetch?: AvFetch;\n" +
             "}\n" +
             "\n" +
             (shaped === undefined
@@ -68,41 +73,52 @@ export function emitClientSurfaceModule(contract, names, style) {
                 : "/** The ClientContract, with each shaped Json field's own type. */\n" +
                     `type ShapedContract = ${shaped};\n` +
                     "\n") +
-            `type Grammar = OperationGrammar<${C}>;\n` +
-            `type Resource = ResourceKey<${C}>;\n` +
+            `type Grammar = AvOperationGrammar<${C}>;\n` +
+            `type Resource = AvResourceKey<${C}>;\n` +
             "\n" +
             "/** `avClient.<resource>.<family>.<variant>(args, options?)`: one call per advertised operation. */\n" +
-            surface("AvClientSurface", "OperationCall<\n" +
+            surface("AvClientSurface", "AvOperationCall<\n" +
                 `\t\t\t\t${C},\n` +
                 "\t\t\t\tR,\n" +
-                "\t\t\t\tGrammar[R][F][V] & OperationIdentity,\n" +
+                "\t\t\t\tGrammar[R][F][V] & AvOperationIdentity,\n" +
                 "\t\t\t\tClientScalarForms,\n" +
                 "\t\t\t\tClientScalarForms,\n" +
-                '\t\t\t\t"data",\n' +
-                "\t\t\t\tCallOptions\n" +
+                "\t\t\t\tAvCallOptions\n" +
                 "\t\t\t>") +
             (interactive
                 ? "\n" +
                     "/** `avClient.tx.<resource>.<family>.<variant>(args)`: a deferred handle; no request. */\n" +
-                    surface("AvTxSurface", "DeferredOperationCall<\n" +
+                    surface("AvTxSurface", "AvDeferredOperationCall<\n" +
                         `\t\t\t\t${C},\n` +
                         "\t\t\t\tR,\n" +
-                        "\t\t\t\tGrammar[R][F][V] & OperationIdentity,\n" +
+                        "\t\t\t\tGrammar[R][F][V] & AvOperationIdentity,\n" +
                         "\t\t\t\tClientScalarForms,\n" +
                         "\t\t\t\tClientScalarForms\n" +
                         "\t\t\t>") +
                     "\n" +
                     "/** Sends the handles as one plan and resolves their results as a typed tuple. */\n" +
-                    "type TransactionCall = <const Steps extends readonly Operation<unknown>[]>(\n" +
+                    "type TransactionCall = <const Steps extends readonly AvOperation<unknown>[]>(\n" +
                     "\tsteps: Steps,\n" +
-                    "\toptions?: CallOptions,\n" +
-                    ") => Promise<TransactionResults<Steps>>;\n"
+                    "\toptions?: AvCallOptions,\n" +
+                    ") => Promise<AvTransactionResults<Steps>>;\n"
                 : "") +
             "\n" +
             "/** The generated client: one property per Resource this deployment's ClientContract advertises. */\n" +
             "export interface AvClient extends AvClientSurface {}\n" +
             "\n" +
-            "/** The generated client. */\n" +
+            (checked
+                ? "/**\n" +
+                    " * The generated client.\n" +
+                    " *\n" +
+                    " * A call runs the ClientContract's field validators before it is sent: one\n" +
+                    " * whose values break a validator, or a check of a shaped Json field, is\n" +
+                    " * refused with the AvValidationError the server would answer (A2004, with\n" +
+                    " * the same issues), and nothing is sent. The client checks each value as\n" +
+                    " * written; the server checks it again after its field pipes, so a field pipe\n" +
+                    " * that normalizes a value must not turn one the client accepted into one the\n" +
+                    " * server refuses. A $ref value in a transaction is the server's to check.\n" +
+                    " */\n"
+                : "/** The generated client. */\n") +
             "export class AvClient {\n" +
             (interactive
                 ? "\t/** Deferred operations, for `transaction`. */\n" +
@@ -117,8 +133,13 @@ export function emitClientSurfaceModule(contract, names, style) {
             "\t\tconst connect = (): TransportConnection => ({ entrypoint, fetch: platformFetch(given) });\n" +
             "\t\tfor (const [resource, families] of operationTree(\n" +
             "\t\t\t(resource, family, variant): OperationMethod =>\n" +
-            "\t\t\t\tasync (args = {}, callOptions = {}) =>\n" +
-            "\t\t\t\t\texecute(connect(), resource, family, variant, args, callOptions),\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),\n") +
             "\t\t)) {\n" +
             "\t\t\tObject.defineProperty(this, propertyOf(resource), { value: families, enumerable: true });\n" +
             "\t\t}\n" +
@@ -133,8 +154,10 @@ 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: CallOptions = {}) =>\n" +
-                    "\t\t\t\trunTransaction(connect(), steps, callOptions),\n" +
+                    "\t\t\tvalue: async (steps: unknown, callOptions: AvCallOptions = {}) =>\n" +
+                    (checked
+                        ? "\t\t\t\trunTransaction(connect(), steps, callOptions, checkPlan),\n"
+                        : "\t\t\t\trunTransaction(connect(), steps, callOptions),\n") +
                     "\t\t});\n"
                 : "") +
             "\t}\n" +
@@ -142,7 +165,7 @@ export function emitClientSurfaceModule(contract, names, style) {
             "\n" +
             "/**\n" +
             " * One frozen object per Resource, one per family under it, one member per\n" +
-            " * advertised variant — by wire name; the caller places each Resource.\n" +
+            " * advertised variant, by wire name; the caller places each Resource.\n" +
             " */\n" +
             "function operationTree<M>(member: (resource: string, family: string, variant: string) => M): Map<string, object> {\n" +
             "\tconst resources = new Map<string, Map<string, Record<string, M>>>();\n" +
@@ -162,7 +185,7 @@ export function emitClientSurfaceModule(contract, names, style) {
             "}\n" +
             "\n" +
             "/** One advertised operation, as the runtime calls it: the types are the surface's. */\n" +
-            "type OperationMethod = (args?: Readonly<Record<string, unknown>>, options?: CallOptions) => Promise<unknown>;\n" +
+            "type OperationMethod = (args?: Readonly<Record<string, unknown>>, options?: AvCallOptions) => Promise<unknown>;\n" +
             "\n" +
             "/** The Resources reached by a property other than their wire name. */\n" +
             `const RENAMED_PROPERTIES: Readonly<Record<string, string>> = {${renamedEntries}};\n` +
@@ -174,11 +197,11 @@ export function emitClientSurfaceModule(contract, names, style) {
             "\n" +
             "/**\n" +
             " * The fetch a call uses: the one the client was given, else the\n" +
-            " * platform's, read when the call is made — so importing the client never\n" +
+            " * platform's, read when the call is made. Importing the client never\n" +
             " * fails where there is no fetch, and a call does, saying why.\n" +
             " */\n" +
-            "function platformFetch(given: Fetch | undefined): Fetch {\n" +
-            "\tconst found = given ?? (globalThis as { readonly fetch?: Fetch }).fetch;\n" +
+            "function platformFetch(given: AvFetch | undefined): AvFetch {\n" +
+            "\tconst found = given ?? (globalThis as { readonly fetch?: AvFetch }).fetch;\n" +
             '\tif (typeof found !== "function") {\n' +
             '\t\tthrow new TypeError("No fetch is available here; pass one: new AvClient({ fetch }).");\n' +
             "\t}\n" +
@@ -189,12 +212,12 @@ export function emitClientSurfaceModule(contract, names, style) {
             "const avClient: AvClient = new AvClient();\n" +
             "export default avClient;\n" +
             "\n" +
-            "type Identity<F extends OperationFamily, V extends string> = Extract<\n" +
-            "\tOperationIdentity,\n" +
+            "type Identity<F extends AvOperationFamily, V extends string> = Extract<\n" +
+            "\tAvOperationIdentity,\n" +
             "\t{ readonly family: F; readonly variant: V }\n" +
             ">;\n" +
             "\n" +
-            "/** A Resource's default record — `find.unique` with no projection. */\n" +
+            "/** A Resource's default record: `find.unique` with no projection. */\n" +
             "export type ResourceRecord<R extends Resource> = AdmittedOperationResult<\n" +
             `\t${C},\n` +
             "\tR,\n" +
@@ -206,11 +229,11 @@ export function emitClientSurfaceModule(contract, names, style) {
             "/** One argument of one of a Resource's operations, present. */\n" +
             "export type ResourceArgument<\n" +
             "\tR extends Resource,\n" +
-            "\tF extends OperationFamily,\n" +
+            "\tF extends AvOperationFamily,\n" +
             "\tV extends string,\n" +
             "\tK extends string,\n" +
             "> = ArgumentOf<\n" +
-            `\tOperationArgumentsFor<${C}, R, Identity<F, V>, ClientScalarForms>,\n` +
+            `\tAvOperationArgumentsFor<${C}, R, Identity<F, V>, ClientScalarForms>,\n` +
             "\tK\n" +
             ">;\n" +
             "\n" +

package/dist/emit/client-tree.emitter.d.ts

@@ -1,8 +1,8 @@
-import type { ClientContract } from "@aventara/core";
+import type { AvContractClient } from "@aventara/core";
 import type { ClientEntrypoint } from "../config/client-config.interface.js";
 import { type ClientEmission } from "./emitted-tree.interface.js";
 import { type ClientModuleStyle } from "./module-style.interface.js";
 /**
- * @throws GeneratedNameError when a name cannot be emitted, even renamed.
+ * @throws AvGeneratedNameError when a name cannot be emitted, even renamed.
  */
-export declare function emitClientTree(contract: ClientContract, entrypoint: ClientEntrypoint, style: ClientModuleStyle): ClientEmission;
+export declare function emitClientTree(contract: AvContractClient, entrypoint: ClientEntrypoint, style: ClientModuleStyle): ClientEmission;

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

@@ -5,6 +5,7 @@ import { emitDerivationModules } from "./derivation.emitter.js";
 import { 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";
@@ -13,8 +14,9 @@ import { emitScalarCodecModule } from "./scalar.codec.js";
 import { emitTransactionModules } from "./transaction.emitter.js";
 export function emitClientTree(contract, entrypoint, style) {
     const names = deriveEmittedNames(contract);
+    const derivation = emitDerivationModules();
     const generated = [
-        ...emitDerivationModules(),
+        ...derivation,
         emitClientSurfaceModule(contract, names, style),
         emitContractCarrierModule(contract),
         emitDescriptorModule(contract),
@@ -28,6 +30,7 @@ export function emitClientTree(contract, entrypoint, style) {
         ...(contract.transactions === "interactive"
             ? emitTransactionModules(style)
             : []),
+        ...emitFieldCheckModules(contract, style, new Set(derivation.map((module) => module.path))),
     ];
     const files = [
         { path: CLIENT_ENTRY_FILE, source: clientEntrySource(style) },
@@ -49,12 +52,12 @@ function clientEntrySource(style) {
     const specifier = moduleSpecifierWriter(style);
     const from = (module) => specifier(`./${GENERATED_DIRECTORY}/${module.replace(/\.d\.ts$|\.ts$/, "")}`);
     return (`export { default } from ${from("client.ts")};\n` +
-        `export {\n\tAvClient,\n\ttype AvClientOptions,\n\ttype CallOptions,\n} from ${from("client.ts")};\n` +
-        `export type { Fetch } from ${from("runtime/transport.ts")};\n` +
-        `export type { Operation } from ${from("derivation/transactions/deferred-operation.d.ts")};\n` +
+        `export {\n\tAvClient,\n\ttype AvClientOptions,\n\ttype AvCallOptions,\n} from ${from("client.ts")};\n` +
+        `export type { AvFetch } from ${from("runtime/transport.ts")};\n` +
+        `export type { AvOperation } from ${from("derivation/transactions/deferred-operation.d.ts")};\n` +
         `export type * from ${from("types.d.ts")};\n` +
         `export * from ${from("enums.ts")};\n` +
-        `export { Decimal } from ${from("runtime/decimal.ts")};\n` +
+        `export { AvDecimal } from ${from("runtime/decimal.ts")};\n` +
         `export {\n${errorsModuleExports()
             .map((name) => `\t${name},\n`)
             .join("")}} from ${from("runtime/errors.ts")};\n`);

package/dist/emit/contract-carrier.emitter.d.ts

@@ -1,5 +1,5 @@
-import type { ClientContract } from "@aventara/core";
+import type { AvContractClient } from "@aventara/core";
 import type { EmittedModule } from "./emitted-tree.interface.js";
 /** `generated/contract.ts`, before the banner. */
-export declare function emitContractCarrierModule(contract: ClientContract): EmittedModule;
-export declare function parseContractCarrier(text: string): Promise<ClientContract | undefined>;
+export declare function emitContractCarrierModule(contract: AvContractClient): EmittedModule;
+export declare function parseContractCarrier(text: string): Promise<AvContractClient | undefined>;

package/dist/emit/derivation.emitter.js

@@ -9,6 +9,7 @@ export const DERIVATION_ROOTS = [
     "operations/operation-call",
     "operations/operation-identity",
     "operations/operation-result",
+    "operations/validation-code",
     "transactions/deferred-operation",
     "transactions/transaction-reference",
 ];

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

@@ -1,4 +1,4 @@
-import type { ClientContract } from "@aventara/core";
+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: ClientContract): EmittedModule;
+export declare function emitDescriptorModule(contract: AvContractClient): EmittedModule;

package/dist/emit/descriptor.emitter.js

@@ -31,7 +31,7 @@ export function emitDescriptorModule(contract) {
         path: "runtime/descriptor.ts",
         source: "/**\n" +
             " * A result field the decoder revives from its wire string, or a relation\n" +
-            " * it recurses into, read as the relation's target Resource — `many` saying the\n" +
+            " * it recurses into, read as the relation's target Resource; `many` says the\n" +
             " * value is a list, `{ data, count }` or `{ count }` rather than one record.\n" +
             " */\n" +
             "export type FieldDecoding =\n" +

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/codec.ts" | "runtime/decimal.ts" | "runtime/descriptor.ts" | "runtime/errors.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/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 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/enum.emitter.d.ts

@@ -1,4 +1,4 @@
-import type { ClientContract } from "@aventara/core";
+import type { AvContractClient } from "@aventara/core";
 import type { EmittedModule } from "./emitted-tree.interface.js";
 import { type EmittedNames } from "./name.deriver.js";
-export declare function emitEnumsModule(contract: Pick<ClientContract, "enums">, names: EmittedNames): EmittedModule;
+export declare function emitEnumsModule(contract: Pick<AvContractClient, "enums">, names: EmittedNames): EmittedModule;

package/dist/emit/field-check.emitter.d.ts

@@ -0,0 +1,21 @@
+import type { AvContractClient } from "@aventara/core";
+import type { EmittedModule } from "./emitted-tree.interface.js";
+import { type ClientModuleStyle } from "./module-style.interface.js";
+/** Where `@aventara/core` publishes the evaluator's source, relative to its package root. */
+export declare const EVALUATOR_SOURCE = "src/runtime/field-check.evaluator.ts";
+/** Reads the evaluator's published source; `undefined` when core publishes none. */
+export type EvaluatorSourceReader = () => string | undefined;
+/** The evaluator's source as the `@aventara/core` this package resolves publishes it. */
+export declare function publishedCoreEvaluator(): EvaluatorSourceReader;
+/** Whether the ClientContract carries any check: a field's validators or a Json Shape node's. */
+export declare function contractHasFieldChecks(contract: AvContractClient): boolean;
+/**
+ * The two field check modules, or none when the contract carries no check.
+ *
+ * @param derivation the declaration paths the tree copies under `derivation/`
+ *   (`derivation/contracts/field-check.d.ts`, …): the evaluator's type imports
+ *   must name one of them.
+ * @throws Error when the evaluator cannot be copied — a defect of the installed
+ *   `@aventara/core`, never of the consumer's input.
+ */
+export declare function emitFieldCheckModules(contract: AvContractClient, style: ClientModuleStyle, derivation: ReadonlySet<string>, read?: EvaluatorSourceReader): readonly EmittedModule[];