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

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;
@@ -269,24 +273,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,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 {};