@aventara/core 0.1.0-pilot.4 → 1.0.0-rc.1

package/dist/runtime/error-boundary.js

@@ -1,5 +1,5 @@
 import { VALIDATION_CODE_MESSAGES, VALIDATION_CODES, } from "../operations/validation-code.js";
-import { FrameworkError } from "./framework-error.js";
+import { AvError } from "./framework-error.js";
 import { INTERNAL_FAILURE_MESSAGE, internalFailure, OPERATION_CODES, operationFailure, } from "./operation-response.js";
 import { PIPE_OUTPUT_FAILURE_MESSAGE } from "./pipe-output.validator.js";
 export const ADAPTER_FAILURE_MESSAGE = "Adapter execution failed.";
@@ -79,8 +79,11 @@ function projectPath(value) {
 export const OPERATION_ARGUMENTS_PATH = [
     "arguments",
 ];
+export function planStepPath(index) {
+    return ["operations", index];
+}
 export function planOperationArgumentsPath(index) {
-    return ["operations", index, "args"];
+    return [...planStepPath(index), "args"];
 }
 const UNRESOLVED = Symbol("unresolved-path-segment");
 function readOwnMember(container, key) {
@@ -100,38 +103,43 @@ function readSegment(container, segment) {
     }
     return readOwnMember(container, segment);
 }
-function resolvesAgainstArguments(path, view) {
+function vouchPath(path, view) {
     try {
-        if (path.length < view.path.length) {
-            return false;
-        }
-        for (let index = 0; index < view.path.length; index += 1) {
-            if (path[index] !== view.path[index]) {
-                return false;
-            }
+        const root = [view.path, OPERATION_ARGUMENTS_PATH].find((prefix) => startsWith(path, prefix));
+        if (root === undefined) {
+            return undefined;
         }
         let current = view.arguments;
-        for (let index = view.path.length; index < path.length; index += 1) {
+        for (let index = root.length; index < path.length; index += 1) {
             const segment = path[index];
             if (segment === undefined) {
-                return false;
+                return undefined;
             }
             current = readSegment(current, segment);
             if (current === UNRESOLVED) {
-                return false;
+                return undefined;
             }
         }
-        return true;
+        return [...view.path, ...path.slice(root.length)];
     }
     catch {
-        return false;
+        return undefined;
     }
 }
+function startsWith(path, prefix) {
+    return (path.length >= prefix.length &&
+        prefix.every((segment, index) => path[index] === segment));
+}
 function isValidationCode(value) {
     return (typeof value === "string" &&
         VALIDATION_CODES.includes(value));
 }
-function projectIssue(value, unvouched, view) {
+export const MAX_DEVELOPER_ISSUE_MESSAGE_LENGTH = 1_000;
+function isDeveloperMessage(message) {
+    return (message.length <= MAX_DEVELOPER_ISSUE_MESSAGE_LENGTH &&
+        message.trim().length > 0);
+}
+function projectIssue(value, unvouched, view, author) {
     if (typeof value !== "object" || value === null) {
         return undefined;
     }
@@ -142,23 +150,32 @@ function projectIssue(value, unvouched, view) {
         }
         return undefined;
     }
-    const message = readProperty(value, "message");
+    const supplied = readProperty(value, "message");
     const rawPath = readProperty(value, "path");
-    if (typeof message !== "string") {
+    if (typeof supplied !== "string") {
         return undefined;
     }
-    const owned = VALIDATION_CODE_MESSAGES[code];
+    let message = VALIDATION_CODE_MESSAGES[code];
+    if (author === "developer") {
+        if (isDeveloperMessage(supplied)) {
+            message = supplied;
+        }
+        else {
+            unvouched.push(supplied);
+        }
+    }
     if (rawPath === undefined) {
-        return { code, message: owned };
+        return { code, message };
     }
-    const path = projectPath(rawPath);
-    if (path === undefined || !resolvesAgainstArguments(path, view)) {
+    const projected = projectPath(rawPath);
+    const path = projected === undefined ? undefined : vouchPath(projected, view);
+    if (path === undefined) {
         unvouched.push(rawPath);
-        return { code, message: owned };
+        return { code, message };
     }
-    return { path, code, message: owned };
+    return { path, code, message };
 }
-function projectCause(value, unvouched, view) {
+function projectCause(value, unvouched, view, author) {
     const message = readProperty(value, "message");
     if (typeof message !== "string") {
         return undefined;
@@ -166,7 +183,7 @@ function projectCause(value, unvouched, view) {
     const rawIssues = readList(readProperty(value, "issues"));
     const rawOperation = readProperty(value, "operation");
     const issues = rawIssues
-        ?.map((issue) => projectIssue(issue, unvouched, view))
+        ?.map((issue) => projectIssue(issue, unvouched, view, author))
         .filter((issue) => issue !== undefined);
     return {
         message,
@@ -190,7 +207,7 @@ function readProperty(value, key) {
 }
 function isFrameworkErrorInstance(error) {
     try {
-        return error instanceof FrameworkError;
+        return error instanceof AvError;
     }
     catch {
         return false;
@@ -206,7 +223,7 @@ function isOperationErrorCode(value) {
         OPERATION_CODES.includes(value) &&
         !value.startsWith("A1"));
 }
-function vetDeliberateOutcome(error, view) {
+function vetDeliberateOutcome(error, view, author) {
     if (!isFrameworkErrorInstance(error)) {
         return undefined;
     }
@@ -218,7 +235,7 @@ function vetDeliberateOutcome(error, view) {
         return MALFORMED_OUTCOME;
     }
     const unvouched = [];
-    const cause = projectCause(rawCause, unvouched, view);
+    const cause = projectCause(rawCause, unvouched, view, author);
     return cause === undefined ? MALFORMED_OUTCOME : { code, cause, unvouched };
 }
 function reportUnvouched(outcome, report) {
@@ -226,13 +243,20 @@ function reportUnvouched(outcome, report) {
         report(value, outcome.code);
     }
 }
+function reportDeliberate(thrown, outcome, report) {
+    if (isInternalCode(outcome.code)) {
+        report(thrown, outcome.code, { deliberate: true });
+        return;
+    }
+    reportUnvouched(outcome, report);
+}
 function deliberateFailure(outcome) {
     return operationFailure(outcome.code, isInternalCode(outcome.code)
         ? internalCause(outcome.code, outcome.cause)
         : outcome.cause);
 }
 export function sanitizeOperationFailure(error, origin, report, view) {
-    const outcome = vetDeliberateOutcome(error, view);
+    const outcome = vetDeliberateOutcome(error, view, origin === "adapter" ? "adapter" : "developer");
     if (outcome === undefined) {
         report(error, unexpectedCode(origin));
         return unexpectedFailure(origin);
@@ -240,29 +264,61 @@ export function sanitizeOperationFailure(error, origin, report, view) {
     if (outcome === MALFORMED_OUTCOME) {
         report(error, "A3000");
     }
-    reportUnvouched(outcome, report);
+    else {
+        reportDeliberate(error, outcome, report);
+    }
     return deliberateFailure(outcome);
 }
-export async function resolveOperationFailure(error, filters, context, boundary, report, view) {
-    for (let index = filters.length - 1; index >= 0; index -= 1) {
-        const filter = filters[index];
-        if (filter === undefined) {
-            continue;
-        }
-        const handled = await attemptFilter(filter, error, context, view);
-        if (handled !== undefined) {
-            if (handled === MALFORMED_OUTCOME) {
-                report(error, "A3000");
-            }
-            reportUnvouched(handled, report);
-            return deliberateFailure(handled);
-        }
+export async function resolveOperationFailure(error, filters, context, boundary, report, view, outer) {
+    const failure = { error, view, boundary, report };
+    const handled = await filterChain(filters, context).attempt(error, view, boundary);
+    if (handled !== undefined) {
+        return answerHandled(failure, handled);
+    }
+    return outer === undefined
+        ? sanitizeUnhandled(failure)
+        : outer.defer(failure);
+}
+function answerHandled(failure, handled) {
+    if (handled.outcome === MALFORMED_OUTCOME) {
+        failure.report(failure.error, "A3000");
+    }
+    else {
+        reportDeliberate(handled.returned, handled.outcome, failure.report);
     }
-    return sanitizeOperationFailure(error, boundary.originOf(error), report, view);
+    return deliberateFailure(handled.outcome);
+}
+function sanitizeUnhandled(failure) {
+    return sanitizeOperationFailure(failure.error, failure.boundary.originOf(failure.error), failure.report, failure.view);
+}
+export async function resolveUnhandledFailure(failure, chain) {
+    const handled = await chain.attempt(failure.error, failure.view, failure.boundary);
+    return handled === undefined
+        ? sanitizeUnhandled(failure)
+        : answerHandled(failure, handled);
+}
+export function filterChain(filters, context) {
+    return {
+        attempt: async (error, view, boundary) => {
+            for (let index = filters.length - 1; index >= 0; index -= 1) {
+                const filter = filters[index];
+                if (filter === undefined) {
+                    continue;
+                }
+                const handled = await attemptFilter(filter, error, context, view, boundary);
+                if (handled !== undefined) {
+                    return handled;
+                }
+            }
+            return undefined;
+        },
+    };
 }
-async function attemptFilter(filter, error, context, view) {
+async function attemptFilter(filter, error, context, view, boundary) {
     try {
-        return vetDeliberateOutcome(await filter(error, context), view);
+        const returned = await filter(error, context);
+        const outcome = vetDeliberateOutcome(returned, view, boundary.originOf(returned) === "adapter" ? "adapter" : "developer");
+        return outcome === undefined ? undefined : { returned, outcome };
     }
     catch {
         return undefined;

package/dist/runtime/execution-options.d.ts

@@ -1,13 +1,21 @@
+import type { AvState } from "./request-state.js";
 /**
  * Options for one in-process call: the optional second argument of every
  * `framework.application.*` / `framework.client.*` call and of
  * `framework.transaction`.
  */
-export type ExecutionOptions = {
+export type AvExecutionOptions = {
     /**
      * The id every pipeline context and every diagnostic of this call or run
-     * carries — a correlation id the caller already holds. Omitted, the Framework
+     * carries, such as a correlation id the caller already holds. Omitted, the Framework
      * mints one; the empty string counts as omitted.
      */
     readonly requestId?: string;
+    /**
+     * The call's or run's `ctx.$state`: the one object every stage of it, and
+     * every ctx call those stages make, reads and writes. It is used as it is, not
+     * copied, so the caller sees what the stages wrote. Omitted (or not an
+     * object), the Framework starts the request with `{}`.
+     */
+    readonly state?: AvState & object;
 };

package/dist/runtime/field-check.evaluator.d.ts

@@ -0,0 +1,29 @@
+import type { AvFieldCheck } from "../contracts/field-check.js";
+import type { AvValidationIssue } from "../operations/validation-code.js";
+/** What a check judges: the runtime form of the value it is given. */
+export type FieldCheckSubject = "string" | "number" | "bigint" | "decimal" | "datetime" | "bytes";
+/**
+ * What a check judges on a field of each scalar type that takes checks; a field
+ * of any other type (an enum's) holds a string.
+ */
+export declare const FIELD_CHECK_SUBJECTS: Readonly<Record<string, FieldCheckSubject>>;
+type Path = readonly (string | number)[];
+/**
+ * Whether `value` passes `check`; `true` for a value the check does not judge
+ * (a value of another form, which validation refused before the checks run).
+ */
+export declare function passesFieldCheck(check: AvFieldCheck, value: unknown, subject: FieldCheckSubject): boolean;
+/** The issue of one failed check at `path`: its V-code, zod's check and its parameters. */
+export declare function fieldCheckIssue(check: AvFieldCheck, subject: FieldCheckSubject, path: Path): AvValidationIssue;
+/**
+ * The issues of the checks `value` breaks, one per broken check, in the checks'
+ * order. On a list (`list`), a `list: true` length check judges the list at
+ * `path` and every other check judges each entry, at its index; `null` is no
+ * value and breaks nothing.
+ */
+export declare function fieldCheckIssues(checks: readonly AvFieldCheck[], value: unknown, subject: FieldCheckSubject, path: Path, list: boolean): readonly AvValidationIssue[];
+/** The issues of the checks one value — a whole value, or a list's entry — breaks. */
+export declare function entryCheckIssues(checks: readonly AvFieldCheck[], value: unknown, subject: FieldCheckSubject, path: Path): readonly AvValidationIssue[];
+/** Whether a check judges a list's own length (`AvZ.minItems`/`AvZ.maxItems`). */
+export declare function isListCheck(check: AvFieldCheck): boolean;
+export {};