@aventara/core 1.0.0-rc.0 → 1.0.0-rc.10

package/dist/runtime/error-boundary.d.ts

@@ -1,8 +1,9 @@
 import type { DiagnosticsReporter } from "./diagnostics-reporter.js";
-import type { OperationFailureResponse } from "./operation-response.js";
-import type { Filter, PipelineContext } from "./pipeline.js";
+import { AvError } from "./framework-error.js";
+import type { AvCause, AvOperationErrorCode, AvOperationFailureResponse } from "./operation-response.js";
+import type { AvContext } from "./pipeline.js";
 /** Where an unexpected post-validation exception originated. */
-export type FailureOrigin = "adapter" | "runtime";
+type FailureOrigin = "adapter" | "runtime";
 /** The one generic Adapter-failure text; every unexpected A3001 carries it. */
 export declare const ADAPTER_FAILURE_MESSAGE = "Adapter execution failed.";
 /** One boundary instance belongs to one operation execution. */
@@ -39,18 +40,81 @@ export type CallerArgumentsView = {
  * framework's text for its code and reported to the diagnostics channel.
  */
 export declare const MAX_DEVELOPER_ISSUE_MESSAGE_LENGTH = 1000;
+/** The stable outcome a thrower chose, once the boundary has vetted it. */
+type DeliberateOutcome = {
+    readonly code: AvOperationErrorCode;
+    readonly cause: AvCause;
+    /**
+     * Every issue code, issue path and developer issue message the boundary could
+     * not vouch for, raw and in supplied order.
+     */
+    readonly unvouched: readonly unknown[];
+};
+/**
+ * The refusal code `error` deliberately carries, vetted as every boundary vets
+ * it ({@link vetDeliberateOutcome}): a recognised error code that is no
+ * internal (`A3xxx`) one, with a well-formed cause. `undefined` for anything
+ * else, which the caller answers as the defect it is.
+ */
+export declare function deliberateRefusalCode(error: unknown): AvOperationErrorCode | undefined;
 /**
  * Final framework sanitization, shared by every boundary. A deliberate
- * {@link FrameworkError} carries its own stable outcome; anything else is
+ * {@link AvError} carries its own stable outcome; anything else is
  * replaced by a generic cause so no provider text, stack, path, or secret
  * can cross the response boundary. Total: it never throws.
  */
-export declare function sanitizeOperationFailure(error: unknown, origin: FailureOrigin, report: DiagnosticsReporter, view: CallerArgumentsView): OperationFailureResponse;
+export declare function sanitizeOperationFailure(error: unknown, origin: FailureOrigin, report: DiagnosticsReporter, view: CallerArgumentsView): AvOperationFailureResponse;
+/**
+ * A filter over the context its stage is told: an operation's `AvFilter`,
+ * or a Resource transaction filter, whose context is the plan.
+ */
+type FilterOf<Context> = (error: unknown, context: Context) => AvError | undefined | Promise<AvError | undefined>;
 /**
  * Post-validation exception flow: effective filters are stored as `[root...,
  * scoped...]`, so reverse iteration tries scoped filters in reverse registration
- * order, then root filters in reverse, then final sanitization. A filter handles an
- * error only by returning a {@link FrameworkError}; returning `undefined` or throwing
- * leaves the original error unhandled.
+ * order, then root filters in reverse. An error they leave unhandled goes to
+ * `outer` when there is one (a transaction step's: its Resource transaction
+ * filters, run once the transaction interceptors have unwound), else to final
+ * sanitization. A filter handles an error only by returning a {@link AvError};
+ * returning `undefined` or throwing leaves the original error unhandled.
  */
-export declare function resolveOperationFailure(error: unknown, filters: readonly Filter[], context: PipelineContext, boundary: AdapterBoundary, report: DiagnosticsReporter, view: CallerArgumentsView): Promise<OperationFailureResponse>;
+export declare function resolveOperationFailure<Context = AvContext>(error: unknown, filters: readonly FilterOf<Context>[], context: Context, boundary: AdapterBoundary, report: DiagnosticsReporter, view: CallerArgumentsView, outer?: OuterFailureLayer): Promise<AvOperationFailureResponse>;
+/**
+ * An error a step's own filters left unhandled, with what answering it later
+ * needs: the caller's arguments as the step held them, the step's Adapter
+ * boundary (whose identity says whose words the error is) and its reporter.
+ */
+export type UnhandledFailure = {
+    readonly error: unknown;
+    readonly view: CallerArgumentsView;
+    readonly boundary: AdapterBoundary;
+    readonly report: DiagnosticsReporter;
+};
+/**
+ * Where a transaction step hands an error its own filters left unhandled. It
+ * records the error and answers a provisional failure, which fails the step; the
+ * transaction replaces it with the transaction filters' answer.
+ */
+export type OuterFailureLayer = {
+    readonly defer: (failure: UnhandledFailure) => AvOperationFailureResponse;
+};
+/**
+ * An unhandled step error through `chain` (the transaction filters, the first
+ * that handles it wins), then final sanitization.
+ */
+export declare function resolveUnhandledFailure(failure: UnhandledFailure, chain: FilterChain): Promise<AvOperationFailureResponse>;
+/**
+ * A chain of filters and the context they are told, tried in reverse: the first
+ * that returns an {@link AvError} handles the error.
+ */
+type FilterChain = {
+    readonly attempt: (error: unknown, view: CallerArgumentsView, boundary: AdapterBoundary) => Promise<FilteredOutcome | undefined>;
+};
+/** The chain of `filters` (stored outer to inner, tried in reverse), told `context`. */
+export declare function filterChain<Context>(filters: readonly FilterOf<Context>[], context: Context): FilterChain;
+/** What a filter returned, and the deliberate outcome it vets as. */
+type FilteredOutcome = {
+    readonly returned: unknown;
+    readonly outcome: DeliberateOutcome;
+};
+export {};

package/dist/runtime/error-boundary.js

@@ -1,5 +1,6 @@
+import { isDatabaseRefusalMessage } from "../operations/database-refusal.js";
 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.";
@@ -164,6 +165,9 @@ function projectIssue(value, unvouched, view, author) {
             unvouched.push(supplied);
         }
     }
+    else if (isDatabaseRefusalMessage(code, supplied)) {
+        message = supplied;
+    }
     if (rawPath === undefined) {
         return { code, message };
     }
@@ -207,7 +211,7 @@ function readProperty(value, key) {
 }
 function isFrameworkErrorInstance(error) {
     try {
-        return error instanceof FrameworkError;
+        return error instanceof AvError;
     }
     catch {
         return false;
@@ -238,6 +242,14 @@ function vetDeliberateOutcome(error, view, author) {
     const cause = projectCause(rawCause, unvouched, view, author);
     return cause === undefined ? MALFORMED_OUTCOME : { code, cause, unvouched };
 }
+export function deliberateRefusalCode(error) {
+    const outcome = vetDeliberateOutcome(error, { path: [], arguments: undefined }, "developer");
+    return outcome === undefined ||
+        outcome === MALFORMED_OUTCOME ||
+        isInternalCode(outcome.code)
+        ? undefined
+        : outcome.code;
+}
 function reportUnvouched(outcome, report) {
     for (const value of outcome.unvouched) {
         report(value, outcome.code);
@@ -269,24 +281,50 @@ export function sanitizeOperationFailure(error, origin, report, view) {
     }
     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, boundary);
-        if (handled !== undefined) {
-            if (handled.outcome === MALFORMED_OUTCOME) {
-                report(error, "A3000");
-            }
-            else {
-                reportDeliberate(handled.returned, handled.outcome, report);
-            }
-            return deliberateFailure(handled.outcome);
-        }
+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, boundary) {
     try {

package/dist/runtime/error-guidance.d.ts

@@ -0,0 +1,12 @@
+/** Why a code is answered, and what the one who meets it should do. */
+export type ErrorCodeGuidance = {
+    /** What typically produced the code, in a sentence or two. */
+    readonly cause: string;
+    /** What to change so it does not happen again. */
+    readonly fix: string;
+};
+/** Guidance for a code whose table holds no message of its own. */
+export type ErrorCodeDescription = ErrorCodeGuidance & {
+    /** The code's meaning, in one short sentence. */
+    readonly message: string;
+};

package/dist/runtime/error-guidance.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/error.catalog.d.ts

@@ -0,0 +1,49 @@
+import type { AvAdapterDiscoveryDiagnosticCode } from "../adapters/adapter-discovery-diagnostic.js";
+import type { AvContractCompilerDiagnosticCode } from "../compiler/contract-compiler-diagnostic.js";
+import type { AvConfigDiagnosticCode } from "../config/config-diagnostic.js";
+import type { AvConstructionStage } from "../framework/framework-construction.error.js";
+import { type AvValidationCode } from "../operations/validation-code.js";
+import { type AvOperationCode } from "./operation-response.js";
+/**
+ * The documentation page every catalog entry links into. Each code has its own
+ * anchor there: the code in lower case (`#a2004`, `#config_required`).
+ */
+export declare const ERROR_CODES_DOCS_URL = "https://aventara-framework.vercel.app/docs/error-codes";
+/**
+ * What kind of code an entry is: an outcome code's family (`success` `A1xxx`,
+ * `request` `A2xxx`, `internal` `A3xxx`, `auth` `A4xxx`), a `validation` issue
+ * code (`V1xxx`), or a startup code, by the construction stage that reports it.
+ */
+export type AvErrorKind = "success" | "request" | "internal" | "auth" | "validation" | AvConstructionStage;
+/** Every code the catalog describes: outcome, validation and startup codes. */
+export type AvErrorCatalogCode = AvOperationCode | AvValidationCode | AvConfigDiagnosticCode | AvAdapterDiscoveryDiagnosticCode | AvContractCompilerDiagnosticCode;
+/** One code: what it means, why it happens, what to do, and where it is documented. */
+export type AvErrorCatalogEntry<C extends AvErrorCatalogCode = AvErrorCatalogCode> = {
+    readonly code: C;
+    readonly kind: AvErrorKind;
+    /** Its meaning in one sentence; for a V-code, the framework's message for it. */
+    readonly message: string;
+    /** What typically produces it. */
+    readonly cause: string;
+    /** What to change. */
+    readonly fix: string;
+    /** Its entry on the error-codes page. */
+    readonly docs: string;
+};
+/** The error catalog's type: one entry per code. */
+export type AvErrorCatalog = {
+    readonly [C in AvErrorCatalogCode]: AvErrorCatalogEntry<C>;
+};
+/** The documentation URL of one code: the error-codes page at its anchor. */
+export declare function errorDocsUrl(code: AvErrorCatalogCode): string;
+/**
+ * Every code Aventara answers or refuses with, by code: its `kind`, `message`,
+ * `cause`, `fix` and `docs` URL. An operation's `code`, a validation issue's
+ * `code` and a startup diagnostic's `code` are all keys of it:
+ *
+ * ```ts
+ * AvErrorCatalog[error.code].fix;
+ * AvErrorCatalog.V1000.docs; // https://aventara-framework.vercel.app/docs/error-codes#v1000
+ * ```
+ */
+export declare const AvErrorCatalog: AvErrorCatalog;

package/dist/runtime/error.catalog.js

@@ -0,0 +1,49 @@
+import { ADAPTER_DISCOVERY_DIAGNOSTIC_GUIDANCE } from "../adapters/adapter-discovery-diagnostic.guidance.js";
+import { CONTRACT_COMPILER_DIAGNOSTIC_GUIDANCE } from "../compiler/contract-compiler-diagnostic.guidance.js";
+import { CONFIG_DIAGNOSTIC_GUIDANCE } from "../config/config-diagnostic.guidance.js";
+import { VALIDATION_CODE_GUIDANCE } from "../operations/validation-code.guidance.js";
+import { VALIDATION_CODE_MESSAGES, VALIDATION_CODES, } from "../operations/validation-code.js";
+import { OPERATION_CODE_GUIDANCE } from "./operation-code.guidance.js";
+import { OPERATION_CODES } from "./operation-response.js";
+export const ERROR_CODES_DOCS_URL = "https://aventara-framework.vercel.app/docs/error-codes";
+export function errorDocsUrl(code) {
+    return `${ERROR_CODES_DOCS_URL}#${code.toLowerCase()}`;
+}
+const OUTCOME_KIND = {
+    "1": "success",
+    "2": "request",
+    "3": "internal",
+    "4": "auth",
+};
+function entry(code, kind, description) {
+    return Object.freeze({
+        code,
+        kind,
+        message: description.message,
+        cause: description.cause,
+        fix: description.fix,
+        docs: errorDocsUrl(code),
+    });
+}
+function entriesOf(table, kind) {
+    return Object.keys(table).map((code) => [
+        code,
+        entry(code, kind, table[code]),
+    ]);
+}
+export const AvErrorCatalog = Object.freeze(Object.fromEntries([
+    ...OPERATION_CODES.map((code) => [
+        code,
+        entry(code, OUTCOME_KIND[code[1]], OPERATION_CODE_GUIDANCE[code]),
+    ]),
+    ...VALIDATION_CODES.map((code) => [
+        code,
+        entry(code, "validation", {
+            message: VALIDATION_CODE_MESSAGES[code],
+            ...VALIDATION_CODE_GUIDANCE[code],
+        }),
+    ]),
+    ...entriesOf(CONFIG_DIAGNOSTIC_GUIDANCE, "configuration"),
+    ...entriesOf(ADAPTER_DISCOVERY_DIAGNOSTIC_GUIDANCE, "discovery"),
+    ...entriesOf(CONTRACT_COMPILER_DIAGNOSTIC_GUIDANCE, "contract-compilation"),
+]));

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

@@ -1,13 +1,29 @@
+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;
+    /**
+     * The principal the call or run is checked as by the configuration's
+     * `policy`. An application call names one to opt in: left out, it is server
+     * code and the policy does not check it. A `framework.client.*` call is
+     * checked either way, and `as` replaces the principal `policy.principal`
+     * would derive from its state. `null` is the anonymous principal.
+     */
+    readonly as?: unknown;
 };

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

@@ -0,0 +1,27 @@
+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[];
+export {};