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

package/dist/runtime/field-validator.runtime.js

@@ -1,4 +1,5 @@
-import { validatedFieldsOf, } from "../compiler/field-validator.compiler.js";
+import { hasFieldValidators, validatedFieldsOf, } from "../compiler/field-validator.compiler.js";
+import { AvComputedValueError } from "./computed-value.error.js";
 import { entryCheckIssues, fieldCheckIssues } from "./field-check.evaluator.js";
 import { isPlainRecord, valueAt, writeRecordPathsOf, } from "./field-stage.runtime.js";
 import { nestedWriteTargetsOf } from "./nested-write.walker.js";
@@ -14,7 +15,10 @@ function rulesOf(contract, compiled, resource, name) {
     const field = fields !== undefined && Object.hasOwn(fields, name)
         ? fields[name]
         : undefined;
-    if (field?.kind === "scalar" && field.json !== undefined) {
+    if (field === undefined) {
+        return undefined;
+    }
+    if (field.kind === "scalar" && field.json !== undefined) {
         return { kind: "shape", field };
     }
     const checks = Object.hasOwn(compiled, name) ? compiled[name] : undefined;
@@ -36,17 +40,17 @@ function entryIssues(rules, entry, at) {
     const { compiled } = rules;
     return entryCheckIssues(compiled.checks, entry, compiled.subject ?? "string", at);
 }
-function recordIssues(contract, resource, records, args, argumentsPath, select) {
+function recordIssues(contract, resource, records, args, argumentsPath, select, deferred) {
     const compiled = validatedFieldsOf(contract, resource);
     const issues = [];
-    for (const path of records) {
+    for (const { path, stage } of records) {
         const record = valueAt(args, path);
         if (!isPlainRecord(record)) {
             continue;
         }
         for (const name of Object.keys(record)) {
             const rules = rulesOf(contract, compiled, resource, name);
-            if (rules === undefined) {
+            if (rules === undefined || deferred?.(resource, stage, name) === true) {
                 continue;
             }
             const fieldPath = [...path, name];
@@ -78,10 +82,45 @@ function recordIssues(contract, resource, records, args, argumentsPath, select)
     }
     return issues;
 }
-export function fieldValidatorIssues(contract, references, request, args, argumentsPath, select) {
-    const issues = recordIssues(contract, request.resource, writeRecordPathsOf(request.family, args), args, argumentsPath, select);
+export function fieldValidatorIssues(contract, references, request, args, argumentsPath, select, deferred) {
+    const issues = recordIssues(contract, request.resource, writeRecordPathsOf(request.family, args).map((path) => ({
+        path,
+        stage: request.family === "create" || path[0] === "create"
+            ? "create"
+            : "update",
+    })), args, argumentsPath, select, deferred);
     for (const target of nestedWriteTargetsOf(contract, references, request, args)) {
-        issues.push(...recordIssues(contract, target.resource, target.records.map((site) => site.path), args, argumentsPath, select));
+        issues.push(...recordIssues(contract, target.resource, target.records, args, argumentsPath, select, deferred));
     }
     return issues;
 }
+function holdsField(contract, resource, field) {
+    const fields = Object.hasOwn(contract.resources, resource)
+        ? contract.resources[resource]?.fields
+        : undefined;
+    return fields !== undefined && Object.hasOwn(fields, field);
+}
+export function hiddenFieldRefusal(contracts, references, request, args, argumentsPath) {
+    const { core, active } = contracts;
+    if (core === active || !hasFieldValidators(core)) {
+        return undefined;
+    }
+    const judged = [];
+    const issues = fieldValidatorIssues(core, references, request, args, argumentsPath, () => true, (resource, stage, field) => {
+        if (holdsField(active, resource, field)) {
+            return true;
+        }
+        judged.push({ resource, stage, field });
+        return false;
+    });
+    const [first] = issues;
+    if (first === undefined) {
+        return undefined;
+    }
+    const path = first.path ?? [];
+    const at = judged.find(({ field }) => path.includes(field)) ?? judged[0];
+    if (at === undefined) {
+        return undefined;
+    }
+    return new AvComputedValueError(at.resource, at.field, at.stage, issues, `compute.${at.stage} on ${at.resource}.${at.field}, a field the ${request.origin} layer hides, returned a value its validators refuse (${first.code}: ${first.message})`);
+}

package/dist/runtime/json-value.d.ts

@@ -1,15 +1,20 @@
 /**
  * A JSON value: the form of the `json` scalar, in arguments and results.
  *
- * A `Date`, a `bigint`, a `Uint8Array`, a {@link AvDecimal}, any other class
- * instance and an `undefined` property are refused (`V1001`), as are a
- * non-finite `number` (`V1004`) and a cycle (`V1001`).
+ * A `Date`, a `bigint`, a `Uint8Array`, a {@link AvDecimal} and any other class
+ * instance are refused (`V1001`), as are a non-finite `number` (`V1004`) and a
+ * cycle (`V1001`). An `undefined` inside the value is what JSON makes of it: a key
+ * holding it is left out, an array element holding it (or a hole) is `null`. The
+ * type admits a key holding `undefined`, so an object with an optional property is
+ * a JSON value; an array element stays typed without it, as JSON has no such
+ * value.
  *
- * Results are fresh plain copies, so mutating one is safe.
+ * Results are fresh plain copies, so mutating one is safe; a result never holds a
+ * key whose value is `undefined`.
  *
  * A `json` field's value is this without its top-level `null`: a field-level
  * `null` is the field's absence, which only `nullable: true` admits.
  */
 export type AvJsonValue = string | number | boolean | null | readonly AvJsonValue[] | {
-    readonly [key: string]: AvJsonValue;
+    readonly [key: string]: AvJsonValue | undefined;
 };

package/dist/runtime/level-lifecycle.runtime.d.ts

@@ -17,8 +17,8 @@ export type NextReuse<Refusal extends Error = Error> = {
  * Runs `levels`' lifecycle around `inner`: every interceptor, outer to inner,
  * around every before hook, `inner`, and every after hook. `settle` turns what
  * `inner` or an interceptor below resolved into what the stage above sees (the
- * operation read-materializes it). An after hook is told a deep-frozen copy of
- * the result; the result itself goes on to the interceptors, which may answer a
+ * operation read-materializes it). Each after hook is told its own deep-frozen
+ * copy of the result; the result itself goes on to the interceptors, which may answer a
  * different one. Every `next()` is single use: a second call rejects with
  * `refuse()`'s error, recorded in `reuse`, and runs nothing.
  */

package/dist/runtime/level-lifecycle.runtime.js

@@ -20,11 +20,8 @@ export async function runLevelLifecycle(levels, context, inner, settle, reuse, r
         }
         const result = await settle(await inner());
         const after = [...levels].reverse().flatMap((level) => level.hooks.after);
-        if (after.length > 0) {
-            const told = frozenCopy(result);
-            for (const hook of after) {
-                await hook(told, context());
-            }
+        for (const hook of after) {
+            await hook(frozenCopy(result), context());
         }
         return result;
     };

package/dist/runtime/mutation-planner.js

@@ -1,7 +1,8 @@
 import { lookupField, lookupResource } from "../contracts/contract-lookup.js";
 import { AvComputedValueError } from "./computed-value.error.js";
 import { replaceAt, valueAt } from "./field-stage.runtime.js";
-import { jsonShapeIssues, normalizeScalarFieldValue, } from "./scalar-runtime.js";
+import { frozenCopy } from "./readonly-value.js";
+import { normalizeScalarFieldValue } from "./scalar-runtime.js";
 function writeScalarField(contracts, resourceName, fieldName) {
     const field = lookupField(lookupResource(contracts.core, resourceName), fieldName) ??
         lookupField(lookupResource(contracts.active, resourceName), fieldName);
@@ -57,7 +58,7 @@ async function computeRecord(contracts, compute, resourceName, stage, data, cont
             if (field === undefined) {
                 continue;
             }
-            const snapshot = Object.freeze({ ...logicalData });
+            const snapshot = frozenCopy(logicalData);
             const computed = await callback({
                 field: fieldName,
                 value: snapshot[fieldName],
@@ -79,18 +80,6 @@ async function computeRecord(contracts, compute, resourceName, stage, data, cont
             if (!validation.ok) {
                 throw new AvComputedValueError(resourceName, fieldName, stage, validation.issues);
             }
-            const shapeIssues = jsonShapeIssues(field, validation.value, [
-                "resources",
-                resourceName,
-                "fields",
-                fieldName,
-                "pipelines",
-                "compute",
-                stage,
-            ]);
-            if (shapeIssues.length > 0) {
-                throw new AvComputedValueError(resourceName, fieldName, stage, shapeIssues);
-            }
             logicalData[fieldName] = validation.value;
         }
     }

package/dist/runtime/operation-code.guidance.d.ts

@@ -0,0 +1,6 @@
+import type { ErrorCodeDescription } from "./error-guidance.js";
+import type { AvOperationCode } from "./operation-response.js";
+/** Meaning, cause and fix of every outcome code. */
+export declare const OPERATION_CODE_GUIDANCE: {
+    readonly [C in AvOperationCode]: ErrorCodeDescription;
+};

package/dist/runtime/operation-code.guidance.js

@@ -0,0 +1,167 @@
+export const OPERATION_CODE_GUIDANCE = {
+    A1000: {
+        message: "Success.",
+        cause: "A read, a count or another operation without a more specific success code succeeded.",
+        fix: "Nothing: the call succeeded.",
+    },
+    A1001: {
+        message: "No match.",
+        cause: "A first-style operation (find.first, update.first, delete.first) matched no row; data is null and the generated client resolves null.",
+        fix: "Nothing: handle the null result. A unique operation answers A2003 instead.",
+    },
+    A1002: {
+        message: "Created.",
+        cause: "create.one created a row.",
+        fix: "Nothing: the call succeeded.",
+    },
+    A1003: {
+        message: "Created many.",
+        cause: "create.many or create.count created rows.",
+        fix: "Nothing: the call succeeded.",
+    },
+    A1004: {
+        message: "Updated.",
+        cause: "update.first or update.unique updated a row.",
+        fix: "Nothing: the call succeeded.",
+    },
+    A1005: {
+        message: "Updated many.",
+        cause: "update.many or update.count updated rows.",
+        fix: "Nothing: the call succeeded.",
+    },
+    A1006: {
+        message: "Deleted.",
+        cause: "delete.first or delete.unique deleted a row.",
+        fix: "Nothing: the call succeeded.",
+    },
+    A1007: {
+        message: "Deleted many.",
+        cause: "delete.count deleted rows.",
+        fix: "Nothing: the call succeeded.",
+    },
+    A1008: {
+        message: "Upserted.",
+        cause: "upsert.unique created or updated a row.",
+        fix: "Nothing: the call succeeded.",
+    },
+    A1009: {
+        message: "Transaction committed.",
+        cause: "A whole transaction plan committed; data holds one result per step.",
+        fix: "Nothing: the plan committed.",
+    },
+    A2000: {
+        message: "Invalid request.",
+        cause: "The HTTP request cannot be interpreted: malformed JSON, a body that is not a JSON object, an unknown `/_*` path, a body that does not decode in its Content-Encoding, or a missing Aventara-Protocol-Version or Aventara-Contract-Hash header (the message names it).",
+        fix: "Send a JSON object with both identity headers. The generated client does this for you.",
+    },
+    A2001: {
+        message: "Unknown Resource.",
+        cause: 'The Resource is not in the caller\'s contract: misspelt, hidden by exposure, or added to the schema after aventara:prepare last ran. cause.message is "The requested Resource is not available." and the issue is V1005 at `["resource"]`.',
+        fix: "Use the model's exact name. After a schema change run the adapter's generate step (`npm run aventara:prepare` in a scaffolded project), restart, and regenerate the client. A Resource hidden on purpose is reached from server code (framework.application).",
+    },
+    A2002: {
+        message: "Unknown operation.",
+        cause: 'The operation is not available on that Resource: a typo, removed by exposure, an operation the adapter does not offer (such as delete.many), or a ctx.$sql, appTx.$sql or ctx.$transaction the adapter or the layer cannot run. The issue is V1006 at `["family"]` or `["variant"]`.',
+        fix: "Call an operation the contract lists (`GET <api>/_contract`), regenerate a stale client, and check the layer's exemptions and transactionsStyle.",
+    },
+    A2003: {
+        message: "Not found.",
+        cause: "A unique operation (find.unique, update.unique, delete.unique) matched no row, or a $connect names a record that does not exist. The operation fails, so no after hook runs.",
+        fix: "Catch AvNotFoundError, or use a first-style operation, which answers A1001 with null. Check the $connect identifier.",
+    },
+    A2004: {
+        message: "Validation failed.",
+        cause: 'The arguments break a contract rule or a field validator. cause.issues lists each problem by V-code and path; a validator\'s issue also has check and params. The validators judge the values after the pipes and write compute, so a computed value they refuse is here too, at its field. A required create field left out is here (V1000). So is a value the database itself refused: too long for its column or its index, or out of its range (V1004), or holding a character it cannot store or a pattern it cannot read (V1001), with the issue at `["arguments"]`, or at the value where the adapter can place it (a bigint its driver cannot bind), and its message saying what the database refused. So is a record written through a relation that writes that relation, or a field holding its reference, back (V1012, at that field), where the adapter admits no such write.',
+        fix: "Fix the argument each issue's path points at, as its V-code says. A field the server must fill takes a compute.create stage. For a value the database refused, send one its column holds. For a nested write that writes its relation back, leave that field out: the parent supplies it.",
+    },
+    A2005: {
+        message: "Contract mismatch.",
+        cause: "The caller's Aventara-Contract-Hash is not the server's current one: the schema, the configuration, the limits or the exposure changed, or the client targets another deployment.",
+        fix: "Regenerate the client against the running server: `npm run avclient:generate`.",
+    },
+    A2006: {
+        message: "Protocol mismatch.",
+        cause: "Aventara-Protocol-Version is not 1.",
+        fix: "Send `Aventara-Protocol-Version: 1`, or upgrade the client.",
+    },
+    A2007: {
+        message: "Invalid transaction reference.",
+        cause: "A transaction $ref or fingerprint is invalid: the issues are V1010, V1011, V1016, V1017 or V1018, and cause.operation is the step. A $ref with no fingerprint is A2004 / V1000.",
+        fix: "Let the generated client or framework.appTx build plans; check the $ref path and that the referenced step comes earlier.",
+    },
+    A2008: {
+        message: "Conflict.",
+        cause: "A uniqueness or reference constraint failed: a duplicate value, a missing parent, or a $disconnect or $set that would orphan a required child (also through update.first or a developer SQL statement). Sending it again unchanged fails the same way.",
+        fix: "Change the data. For a duplicate, update the existing row or use upsert.unique.",
+    },
+    A2009: {
+        message: "Limit exceeded.",
+        cause: "A contract limit was crossed: nesting depth (V1013), list or plan size (V1014), boolean nodes (V1015) or Json value depth (V1021).",
+        fix: "Ask for less (paginate, split the plan), or raise the limit under `limits`.",
+    },
+    A2010: {
+        message: "Payload too large.",
+        cause: "The decoded request body exceeds maxRequestBytes (default 1048576).",
+        fix: "Send less, or raise limits.maxRequestBytes.",
+    },
+    A2011: {
+        message: "Unsupported media type.",
+        cause: "The body is not application/json, or its Content-Encoding is not gzip, deflate or br.",
+        fix: "Send `Content-Type: application/json`.",
+    },
+    A2012: {
+        message: "Method not allowed.",
+        cause: "The HTTP method does not fit the route; the Allow header names the right one (`POST` on operations and `/_transactions`, `GET` on `/_contract`).",
+        fix: "Use the method the Allow header names.",
+    },
+    A2013: {
+        message: "Concurrent modification.",
+        cause: "A competing writer reached the state first; nothing was written.",
+        fix: "Retry. No retry is automatic.",
+    },
+    A2014: {
+        message: "Stale selection.",
+        cause: "The selected state changed before the write; nothing was written.",
+        fix: "Read again, then retry.",
+    },
+    A3000: {
+        message: "Internal error.",
+        cause: 'An unexpected failure on the server: a stage threw an error that is not an AvError, an interceptor called next() twice, a compute stage reached a write through its read-only ctx, a compute stage returned a value of the wrong type, or a compute.create returned undefined for a required field. cause.message is always "Internal framework error."',
+        fix: "Read the real error in the diagnostics sink (the root `diagnostics` key) or the server log line for the request id, and fix that stage. To answer with a code of your choice, throw an AvError.",
+    },
+    A3001: {
+        message: "Adapter error.",
+        cause: 'A database or ORM failure that is not something the caller can fix. cause.message is always "Adapter execution failed."',
+        fix: "Read the raw error in the diagnostics sink; check the database, its connection and the migration state.",
+    },
+    A3002: {
+        message: "Transaction error.",
+        cause: "Transaction infrastructure failed (commit or rollback, or the transaction expired or was closed under a step), or a Resource transaction interceptor called next() twice or resolved without calling it.",
+        fix: "Read the diagnostics sink. Call next() exactly once in a transaction interceptor; retry an infrastructure failure.",
+    },
+    A3003: {
+        message: "Serialization error.",
+        cause: "A result could not be encoded for transport.",
+        fix: "Read the diagnostics sink; make compute.read stages and Json values return plain data of the field's type.",
+    },
+    A3004: {
+        message: "Pipe output invalid.",
+        cause: 'A server pipe, field pipe or transaction pipe (or write compute) returned arguments the server\'s own contract refuses: a field the Resource does not have, a wrong type, a dropped required field, a reference written together with its relation (V1012), or a changed plan. cause.message is always "A server pipeline produced invalid arguments."',
+        fix: "Read the server log line, which names the pipe, the operation and the path, and fix the pipe. A pipe returns a new object of the same shape, or undefined to keep the arguments.",
+    },
+    A4000: {
+        message: "Unauthenticated.",
+        cause: 'A guard threw new AvError("A4000", ...): authentication is required or failed. The framework never authenticates by itself.',
+        fix: "Send the credentials your guards expect, such as the Authorization header.",
+    },
+    A4001: {
+        message: "Forbidden.",
+        cause: 'A guard returned false ("Operation denied by a framework guard."), a field write guard or a nested write\'s target guard included, or a stage threw A4001.',
+        fix: "Call as a caller the guard admits, or stop sending the guarded field. To answer another code, throw an AvError from the guard.",
+    },
+    A4002: {
+        message: "Policy denied.",
+        cause: 'A guard or hook threw new AvError("A4002", ...) with a policy reason of your own.',
+        fix: "Read cause.message for the policy's reason.",
+    },
+};

package/dist/runtime/operation-runtime.d.ts

@@ -104,7 +104,13 @@ export type ValidatedOperationArguments = {
 };
 /** Validates one operation's arguments through the Framework Validation Layer. */
 export declare function validateOperationRequest(contract: AvContract, request: FrameworkOperationRequest, options?: OperationValidationOptions, write?: NormalizationWrite): ValidatedOperationArguments;
-/** Every sent field's path: a single call's arguments hold no `$ref`. */
+/** The subject a refused output of an operation's pipes is reported under at a plan step. */
+export declare const STEP_PIPES = "Pipes";
+/**
+ * Every sent field's path. A `$ref` is an object of `$`-keys, which no field
+ * pipe or validator takes, so a plan step's literal values before BEGIN are
+ * every field too, wherever a pipe left a reference or a literal.
+ */
 export declare const EVERY_FIELD: () => boolean;
 /**
  * What admission leaves: the deep-frozen arguments every later stage reads, and
@@ -123,16 +129,24 @@ export type AdmittedOperation = {
 export type AdmissionScope = {
     /**
      * The sent values the field pipes and validators take: every one for a single
-     * call, a plan step's literal values before BEGIN, its resolved `$ref` values
-     * at the step.
+     * call and for a plan step before BEGIN (an unresolved `$ref` is an object of
+     * `$`-keys, which they never take), its resolved `$ref` values at the step.
      */
     readonly select: (path: readonly (string | number)[]) => boolean;
     /** Before BEGIN a plan step's `$ref` slots are unresolved: these admit them. */
     readonly validation?: OperationValidationOptions;
+    /**
+     * A plan step or a forced call, admitted before BEGIN: the validators judge
+     * there the sent values no later stage can change (a field with no write
+     * compute stage of its record's phase), so a caller's refusal opens no
+     * transaction. Everything is judged again after write compute.
+     */
+    readonly beforeBegin?: boolean;
 };
 /**
- * Runs an operation's admission — its guards, pipes and validators — and answers
- * the deep-frozen arguments the rest of the operation reads, or the refusal.
+ * Runs an operation's admission — its guards and pipes, and before BEGIN the
+ * validators of the values nothing after it changes — and answers the
+ * deep-frozen arguments the rest of the operation reads, or the refusal.
  */
 export declare function admitOperation<M extends AvAdapterModel>(dependencies: OperationPipelineDependencies<M>, request: StatefulOperationRequest, contract: AvContract, args: unknown, argumentsPath: readonly (string | number)[], report: DiagnosticsReporter, scope: ExecutorScope<M>, admission?: AdmissionScope): Promise<AdmittedOperation>;
 /** How a plan step's arguments were changed between their admission and the step. */
@@ -146,7 +160,7 @@ export type StepChanges = {
 };
 /**
  * A plan step's (or a forced call's) arguments at the step: resolved values
- * through their field stages, and re-checked when a stage changed them.
+ * through their field pipes, and re-checked when a stage changed them.
  */
 export declare function prepareStep<M extends AvAdapterModel>(dependencies: OperationPipelineDependencies<M>, request: StatefulOperationRequest, contract: AvContract, args: unknown, argumentsPath: readonly (string | number)[], report: DiagnosticsReporter, executor: AvAdapterTransactionExecutor<M>, changes: StepChanges, outer: OuterFailureLayer): Promise<AdmittedOperation>;
 /**