@futdevpro/fsm-dynamo 1.20.88 → 1.20.93

package/build-esm/_models/control-models/error.control-model.js

@@ -0,0 +1,787 @@
+import { DyFM_error_defaults } from '../../_collections/constants/error-defaults.const';
+import { DyFM_Log } from '../../_collections/utils/log.util';
+import { DyFM_Object } from '../../_collections/utils/object.util';
+import { DyFM_getLocalStackLocation } from '../../_collections/utils/stack.util';
+import { DyFM_ErrorLevel } from '../../_enums/error-level.enum';
+import { DyFM_LogStyle } from '../../_enums/log-style.enum';
+import { DyFM_Metadata } from '../data-models/metadata.data-model';
+import { DyFM_httpErrorResponse_name } from './http/http-error-response.control-model';
+export const DyFM_errorFlag = 'DYNAMO-ERROR-OBJECT';
+export const DyFM_errorĐFlagParts = [
+    'DyNTS-',
+    'DyFM-',
+    'DyNX_',
+    'DyNM_',
+    'DyBu_',
+    'DyCLI_',
+];
+export class DyFM_Error_ControlModel extends Error {
+    flag = DyFM_errorFlag + '-v2';
+    // ─── DyFM_Metadata mezok (implements DyFM_Metadata) ─────────────────────────
+    // A DyFM_Error_ControlModel mostantol `extends Error` — igy `err instanceof Error === true`, es a
+    // Node 22 strict unhandled-rejection riport a VALODI throw-site stacket mutatja (a korabbi
+    // `extends DyFM_Metadata` mellett a bare-object Promise rejection veletlen specet blame-elt).
+    // A metadata-orokles helyett strukturalisan IMPLEMENTALJUK a DyFM_Metadata-t: a mezoket itt
+    // deklaraljuk, az init-logikat a constructorban a DyFM_Metadata.applyMetadata statikus vegzi.
+    _id;
+    __created;
+    __createdBy;
+    __lastModified;
+    __lastModifiedBy;
+    __v;
+    _deleted;
+    _deletedBy;
+    _archived;
+    _originalId;
+    _errorCode;
+    _errorCodes = [];
+    /**
+     * The TECHNICAL (developer / log) message — e.g. `buildListItem failed`. ⛔ Not for the UI.
+     * `_messages` contains all sub error messages, in reversed order.
+     */
+    _message;
+    _messages = [];
+    /**
+     * The USER-FACING sentence (the `userMessage` setting) — this is what a UI shows, and what the server's
+     * client-safe response keeps. A separate role from the technical `_message`, NOT its predecessor
+     * (BFR-CREDIT-041: the former `@deprecated use _message` pointed consumers to technical text).
+     * Read it from ANY caught error — a `DyFM_Error` or a raw `HttpErrorResponse` — with `DyFM_Error.getUserMessage`.
+     */
+    __userMessage;
+    /** All user-facing messages of the chain, in reversed order (see `__userMessage`). */
+    __userMessages = [];
+    /** message translation code */
+    __userMessageTranslateCode;
+    /**
+     * The public diagnostic context (see `DyFM_Error_Settings.publicContext`), merged along the wrap chain: the inner
+     * error's keys are kept, the outer one's win on a clash.
+     */
+    __publicContext;
+    /** @deprecated Use isHandled; ___handled remains the serialized compatibility key. */
+    ___handled;
+    /** @deprecated Use isLogged; ___logged remains the serialized compatibility key. */
+    ___logged;
+    ___status;
+    ___issuer;
+    ___issuerSystem;
+    ___issuerService;
+    ___systemVersion;
+    error;
+    errors = [];
+    validationErrors;
+    // `stack` az Error-bol jon (`extends Error`) — itt NEM deklaraljuk ujra, kulonben a
+    // class-field-init undefined-dal felulirna a natancsolt stacket a super() utan.
+    __localStack;
+    level;
+    /** @deprecated Use isLevelUpEnabled; levelUpThis remains the serialized compatibility key. */
+    levelUpThis;
+    additionalContent = {};
+    confidentialContent = {};
+    constructor(set) {
+        // az Error-constructort a nyers input-message-dzsel hivjuk (a vegleges _message kesobb all
+        // ossze; a natancsolt Error.message-et a constructor vegen allitjuk ra) — super() KOTELEZOEN
+        // az elso utasitas, a this- erintese elott.
+        super(set?.message);
+        // Keep the historical Error.name for log, telemetry and consumer compatibility. The new
+        // naming-conformant class export points to this same constructor without changing instances.
+        Object.defineProperty(this, 'name', {
+            value: 'DyFM_Error',
+            enumerable: false,
+            writable: true,
+            configurable: true,
+        });
+        // metadata-init: a korabbi `super(set, { issuer })` helyett (a super most az Error),
+        // target-alapon a DyFM_Metadata.applyMetadata statikuson at.
+        DyFM_Metadata.applyMetadata(this, set, {
+            issuer: set?.issuerService ??
+                set?.error?.___issuerService ??
+                DyFM_error_defaults.issuerService,
+        });
+        try {
+            if (!set) {
+                set = {};
+            }
+            /** set simple properties */
+            this.___handled = Boolean(set.handled ?? set.error?.___handled);
+            this.___status = set.status ?? set.error?.___status;
+            this.___issuer = set.issuer ??
+                set.error?.___issuer ??
+                DyFM_error_defaults.issuer;
+            this.___issuerSystem = set.issuerSystem ??
+                set.error?.___issuerSystem ??
+                DyFM_error_defaults.issuerSystem;
+            this.___issuerService = set.issuerService ??
+                set.error?.___issuerService ??
+                DyFM_error_defaults.issuerService;
+            this.___systemVersion = set.systemVersion ??
+                set.error?.___systemVersion ??
+                DyFM_error_defaults.systemVersion;
+            this.__localStack = set?.__localStack ??
+                set.error?.__localStack ??
+                DyFM_getLocalStackLocation();
+            this.validationErrors = set.validationErrors ?? set.error?.validationErrors;
+            this.level = set.level ?? set.error?.level ?? DyFM_ErrorLevel.error;
+            this.levelUpThis = set.levelUpThis;
+            set.allowCircular = set.allowCircular ??
+                set.additionalContent?.allowCircular ??
+                set.error?.additionalContent?.allowCircular ??
+                false;
+            if (set.allowCircular) {
+                this.additionalContent.allowCircular = true;
+            }
+            if (set?.error?.___logged) {
+                this.___logged = true;
+            }
+            if (!set.allowCircular &&
+                set.additionalContent &&
+                Object.keys(set.additionalContent)?.length) {
+                try {
+                    JSON.stringify(set.additionalContent);
+                }
+                catch {
+                    DyFM_Log.error('Internal Dynamo ERROR: additionalContent is not JSON.stringifyable... ' +
+                        '(it will be removed!)', '\nerrorCode:', set.errorCode);
+                    delete set.additionalContent;
+                }
+            }
+            if (!set.allowCircular &&
+                !set.additionalContent?.allowCircular &&
+                set.error?.additionalContent &&
+                !set.error?.additionalContent?.allowCircular &&
+                Object.keys(set.error?.additionalContent)?.length) {
+                try {
+                    JSON.stringify(set.error?.additionalContent);
+                }
+                catch {
+                    DyFM_Log.error('Internal Dynamo ERROR: additionalContent is not JSON.stringifyable... ' +
+                        '(it will be removed!)', '\nerrorCode:', set.errorCode);
+                    delete set.error?.additionalContent;
+                }
+            }
+            // ADDITIONAL CONTENT
+            if (set.error?.additionalContent) {
+                Object.assign(this.additionalContent, set.error?.additionalContent);
+            }
+            if (set.additionalContent) {
+                Object.assign(this.additionalContent, set.additionalContent);
+            }
+            // CONFIDENTIAL CONTENT
+            if (set.error?.confidentialContent) {
+                Object.assign(this.confidentialContent, set.error?.confidentialContent);
+            }
+            if (set.confidentialContent) {
+                Object.assign(this.confidentialContent, set.confidentialContent);
+            }
+            // ERROR CODE
+            if (!set.errorCode) {
+                set.errorCode = DyFM_error_defaults.errorCode;
+            }
+            /** set default error (self defined) */
+            if (!set.error) {
+                set.error = new Error();
+                const errorStack = set.error.stack?.split('\n');
+                errorStack.splice(1, 1);
+                set.error.stack = errorStack.join('\n');
+            }
+            if (set?.stack) {
+                this.stack = set?.stack;
+            }
+            else if (set.error?.stack) {
+                this.stack = set.error?.stack;
+            }
+            else if (set.error?.name === DyFM_httpErrorResponse_name &&
+                set.error?.error?.stack) {
+                this.stack = set.error?.error?.stack;
+            }
+            else {
+                this.stack = new Error().stack;
+            }
+            /**
+             * BFR-CCAPREVISIONED-007 — the own chain level of a PLAIN (non-Dynamo) source error.
+             *
+             * If `set.error` is a plain `Error` (no `_messages`) and the caller passes its OWN, DIFFERENT
+             * message, the source error's message is a SEPARATE chain level. Previously this message was
+             * pushed into a dead array (`previousErrorCodes`), after the code chain was already built — so
+             * the root-cause message appeared neither in `_messages` nor in `_message`, only in the stack.
+             *
+             * ⚠️ If the caller passes NO own message, the outer level ADOPTS the source message — then
+             * there is no separate level (otherwise the same message would appear twice).
+             *
+             * ⭐ The level also gets a PLACEHOLDER code (`DyFM_error_defaults.errorCode`), exactly like a
+             * Dynamo level without a code: this keeps `_messages` and `_errorCodes` INDEX-ALIGNED, so the
+             * highlighted-code based `_message` selection does not shift.
+             */
+            const plainSourceMessage = !set.error?._messages && typeof set.error !== 'string'
+                ? (set.error?.message || undefined)
+                : undefined;
+            const isPlainSourceLevel = !!plainSourceMessage && !!set.message && set.message !== plainSourceMessage;
+            /** set errorCodes */
+            let previousErrorCodes = [];
+            if (set.error?._errorCodes) {
+                previousErrorCodes.push(...(set.error?._errorCodes ?? []));
+            }
+            if (!set.errorCode) {
+                set.errorCode = DyFM_error_defaults.errorCode;
+            }
+            previousErrorCodes = previousErrorCodes.filter((code) => code !== set.errorCode);
+            // The placeholder is added AFTER the dedupe: for an outer level without a code the dedupe would
+            // otherwise filter it out and the chain would shift (BFR-CCAPREVISIONED-007).
+            this._errorCodes = [
+                ...previousErrorCodes,
+                ...(isPlainSourceLevel ? [DyFM_error_defaults.errorCode] : []),
+                set.errorCode,
+            ].filter(Boolean);
+            /** bring up non NTS and non default first error */
+            const filteredErrorCodes = this._errorCodes.filter((code) => code && code !== DyFM_error_defaults.errorCode &&
+                !DyFM_errorĐFlagParts.some((part) => code.includes(part)));
+            // Fallback: the first REAL code. The BFR-CCAPREVISIONED-007 placeholder sits at index 0 of a plain-source
+            // chain; when every real code is a framework (e.g. DyNTS) code, `_errorCodes[0]` would surface the
+            // placeholder instead of the caller's code (measured: nts DataService / ClientSafeError specs).
+            this._errorCode = filteredErrorCodes[0] ??
+                this._errorCodes?.find((code) => code !== DyFM_error_defaults.errorCode) ??
+                this._errorCodes?.[0];
+            // the message follows the highlighted code, also when only framework codes are present — otherwise the
+            // plain-source chain level (BFR-CCAPREVISIONED-007) at index 0 would become the primary message
+            const highlightedErrorCodeIndex = this._errorCodes.findIndex((code) => code === (filteredErrorCodes?.[0] ?? this._errorCode));
+            /** set message */
+            if (!set.message) {
+                if (typeof set.error === 'string') {
+                    /** string error */
+                    set.message = set.error;
+                }
+                else if (!set.error?.flag?.includes('DYNAMO') &&
+                    set.error?.message) {
+                    /** simple - non-dynamo - error */
+                    set.message = set.error?.message;
+                }
+                else if (set.error.stack) {
+                    /** error not defined - self defining */
+                    const posFull = set.error.stack?.split('\n')?.[1]?.split('\\');
+                    if (posFull?.[posFull?.length - 1]) {
+                        set.message = DyFM_error_defaults.message + '; ' + posFull[posFull.length - 1];
+                    }
+                    else {
+                        set.message = DyFM_error_defaults.message;
+                    }
+                }
+            }
+            /** set messages */
+            let previousMessages = [];
+            if (set.error?._messages) {
+                previousMessages.push(...(set.error?._messages ?? []));
+            }
+            else if (isPlainSourceLevel) {
+                // BFR-CCAPREVISIONED-007: the plain source error's message is PART OF THE CHAIN, never lost.
+                previousMessages.push(plainSourceMessage);
+            }
+            previousMessages = previousMessages.filter((msg) => msg !== set.message);
+            this._messages = [...previousMessages, set.message].filter(Boolean);
+            if (-1 < highlightedErrorCodeIndex &&
+                this._messages[highlightedErrorCodeIndex] &&
+                this._messages[highlightedErrorCodeIndex] !== DyFM_error_defaults.message) {
+                this._message = this._messages[highlightedErrorCodeIndex];
+            }
+            else {
+                this._message = this._messages?.[0];
+            }
+            /** @deprecated use _messages instead */
+            let previousUserMessages = [];
+            if (set.error?.__userMessages) {
+                previousUserMessages.push(...(set.error?.__userMessages ?? []));
+            }
+            if (!set.userMessage) {
+                set.userMessage = DyFM_error_defaults.userMessage;
+            }
+            // BFR-FDPTOKENSERVICE-013: (1) a `DyFM_error_defaults.addECToUserMsg === false` globális
+            // kill-switch minden utótagot letilt (a kód a `_errorCode`-ban úgyis ott van);
+            // (2) ha a userMessage MÁR hordoz `ErrorCode:` sort (wrapper-lánc), nem fűzünk újra —
+            // a dupla-fűzés a KÜLSŐ wrapper kódját mutatta a valódi `_errorCode` helyett.
+            if (set.addECToUserMsg &&
+                DyFM_error_defaults.addECToUserMsg !== false &&
+                set.userMessage !== DyFM_error_defaults.userMessage &&
+                set.errorCode &&
+                !set.userMessage.includes('ErrorCode: ')) {
+                set.userMessage += `\n  ErrorCode: ${set.errorCode}`;
+            }
+            previousUserMessages = previousUserMessages.filter((msg) => msg !== set.userMessage);
+            this.__userMessages = [...previousUserMessages, set.userMessage].filter(Boolean);
+            if (-1 < highlightedErrorCodeIndex &&
+                this.__userMessages[highlightedErrorCodeIndex] &&
+                this.__userMessages[highlightedErrorCodeIndex] !== DyFM_error_defaults.userMessage) {
+                this.__userMessage = this.__userMessages[highlightedErrorCodeIndex];
+            }
+            else {
+                this.__userMessage = this.__userMessages.filter((msg) => msg && msg !== DyFM_error_defaults.userMessage)?.[0];
+            }
+            /** set userMessageTranslateCode */
+            set.userMessageTranslateCode =
+                set.userMessageTranslateCode ??
+                    set.error?.__userMessageTranslateCode;
+            /** set the public context — BFR-CCAPREVISIONED-011: carried along the wrap chain, the outer keys win */
+            const innerPublicContext = Reflect.get(Object(set.error), '__publicContext');
+            const publicContext = {
+                ...(DyFM_Error_ControlModel.isPlainObject(innerPublicContext) ? innerPublicContext : {}),
+                ...(DyFM_Error_ControlModel.isPlainObject(set.publicContext) ? set.publicContext : {}),
+            };
+            if (Object.keys(publicContext).length) {
+                this.__publicContext = publicContext;
+            }
+            /** set errors */
+            let previousErrors = [];
+            if (set.error?.errors?.length) {
+                previousErrors.push(...set.error.errors);
+            }
+            else if (typeof set.error?.errors == 'object') {
+                this.additionalContent.errors = set.error.errors;
+            }
+            previousErrors = previousErrors.filter((error) => error !== set.error);
+            this.errors = [...previousErrors, set.error].filter(Boolean);
+            if (set.errors) {
+                if (0 < this.errors.length) {
+                    this.errors.push(...(set.errors ?? []));
+                }
+                else {
+                    this.errors.push(new Error('there are multiple errors. check errors after this one'), ...(set.errors ?? []));
+                }
+            }
+            this.error = this.errors?.[0];
+            this.errors = this.errors.map((subError) => {
+                if (subError?.errors) {
+                    subError = { ...subError };
+                    delete subError.errors;
+                    delete subError.additionalContent;
+                }
+                if (subError.error?.errors) {
+                    subError.error = { ...subError.error };
+                    delete subError.error.errors;
+                    delete subError.error.additionalContent;
+                }
+                return subError;
+            });
+            this.errors = this.errors.filter((error) => Boolean(error) && (error instanceof Error || Boolean(Object.keys(error).length)));
+            // ─── `extends Error` szerializacios igazitasok ─────────────────────────
+            // A natancsolt Error a stacket NON-ENUMERABLE own-property-kent kezeli, igy a
+            // `{ ...this }` spread (getErrorsFlat) es a JSON.stringify (getParsable / perzisztalas)
+            // elejtene. Enumerable-kent ujradefinialjuk, hogy a szerializacios utak megtartsak.
+            if (this.stack !== undefined) {
+                Object.defineProperty(this, 'stack', {
+                    value: this.stack,
+                    enumerable: true,
+                    writable: true,
+                    configurable: true,
+                });
+            }
+            // A natancsolt Error.message-et a sajat _message-unkre allitjuk (NON-enumerable marad,
+            // hogy a szerializalt shape valtozatlan legyen — a forras tovabbra is a _message): igy a
+            // `(err as Error).message` fogyasztok ES a Node 22 unhandled-rejection printer a valodi
+            // uzenetet latjak, nem ures stringet.
+            Object.defineProperty(this, 'message', {
+                value: this._message ?? this.__userMessage ?? '',
+                enumerable: false,
+                writable: true,
+                configurable: true,
+            });
+            DyFM_Object.safeCleanObject(this);
+            if (!set.allowCircular) {
+                this.errors = this.errors.filter((subError) => {
+                    if (subError instanceof Error) {
+                        return true;
+                    }
+                    try {
+                        JSON.stringify(subError);
+                        return true;
+                    }
+                    catch (error) {
+                        DyFM_Log.error('Internal Dynamo ERROR: error is not JSON.stringifyable... ' +
+                            '(it will be removed!)', '\nerrorCode:', subError?._errorCode);
+                        return false;
+                    }
+                });
+            }
+            if (set.modestLog) {
+                console.error(this._message ?? this.__userMessage ?? this.error);
+            }
+            if (set.log) {
+                console.error(this);
+            }
+        }
+        catch (error) {
+            DyFM_Log.H_error('Internal Dynamo ERROR: Failed to create DyFM_Error_ControlModel...' +
+                'error:\n', error, 'stack:', new Error().stack, 'set:', set);
+        }
+    }
+    getErrorSimplified() {
+        return {
+            errorCode: this._errorCode,
+            message: this._message,
+            userMessage: this.__userMessage,
+            stack: this.stack,
+        };
+    }
+    getErrorsFlat() {
+        const error = { ...this };
+        if (error.error?.error) {
+            delete error.error.error;
+        }
+        if (error.error?.errors) {
+            delete error.error.errors;
+        }
+        error.errors = error.errors.map((subError) => error instanceof Error ? error : ({ ...subError }));
+        error.errors.forEach((subError) => {
+            if (subError.errors) {
+                delete subError.errors;
+            }
+            if (subError.error?.errors) {
+                delete subError.error.errors;
+            }
+            if (subError.error?.error) {
+                delete subError.error.error;
+            }
+            if (subError.additionalContent) {
+                delete subError.additionalContent;
+            }
+        });
+        return error;
+    }
+    logShort(title, setLog, forceLog) {
+        if (this.___logged && !forceLog) {
+            DyFM_Log.warn(`logShort: already logged (${this._errorCode})`);
+            return;
+        }
+        /* switch (logType) { */
+        DyFM_Log.testError(title, '\n    ErrorCode:', this._errorCode, '\n    Message:', this._message?.replaceAll?.('\n', '\n      '));
+        if (setLog) {
+            this.___logged = true;
+        }
+    }
+    warnShort(title, setLog, forceLog) {
+        if (this.___logged && !forceLog) {
+            DyFM_Log.warn(`warnShort: already logged (${this._errorCode})`);
+            return;
+        }
+        DyFM_Log.testWarn(title, '\n    ErrorCode:', this._errorCode, '\n    Message:', this._message?.replaceAll?.('\n', '\n      '));
+        if (setLog) {
+            this.___logged = true;
+        }
+    }
+    logSimple(title, logAdditionalContent, forceLog, logNodeModules) {
+        if (this.___logged && !forceLog) {
+            DyFM_Log.warn(`logSimple: already logged ${title} (${this._message}; ${this._errorCode})`);
+            return;
+        }
+        // remove node_modules from stack and replace with '...'
+        /* const stack: string = this.stack?.split?.('\n').map((line: string): string => {
+          if (line.includes('node_modules')) {
+            return '...';
+          }
+          return line;
+        }).filter((line: string, index: number, array: string[]): boolean => {
+          if (line === '...' && index < array.length - 1 && array[index + 1] === '...') {
+            return false;
+          }
+          return true;
+        }).join('\n'); */
+        DyFM_Log.H_error(title, `\n${DyFM_Log.errorStyle}ErrorCode:`, this._errorCode, `\n${DyFM_Log.errorStyle}${DyFM_LogStyle.bold}Message:`, this._message?.replaceAll?.('\n', '\n      '), `\n\n${DyFM_LogStyle.reset}${DyFM_Log.errorStyle}UserMessage:`, this.__userMessage?.replaceAll?.('\n', '\n      '), this.__localStack ?
+            `\n${DyFM_Log.errorStyle}LocalStack:\n      ` + this.__localStack : '', `\n\n${DyFM_Log.errorStyle}Stack:`, this.stack?.replaceAll?.('\n', '\n  '), logAdditionalContent && this.additionalContent ?
+            `\n\n${DyFM_Log.errorStyle}AdditionalContent:\n` + this.additionalContent : '');
+        this.___logged = true;
+    }
+    /* static getSimpleLogContent(error: DyFM_Error_ControlModel): string {
+      return `\n${DyFM_Log.errorStyle}ErrorCode:`, this._errorCode,
+        `\n${DyFM_Log.errorStyle}${DyFM_LogStyle.bold}Message:`,
+          this._message?.replaceAll?.('\n', '\n      '),
+        `\n\n${DyFM_LogStyle.reset}${DyFM_Log.errorStyle}UserMessage:`,
+          this.__userMessage?.replaceAll?.('\n', '\n      '),
+            this.__localStack ?
+              `\n${DyFM_Log.errorStyle}LocalStack:\n      ` + this.__localStack : '',
+        `\n\n${DyFM_Log.errorStyle}Stack:`, this.stack?.replaceAll?.('\n', '\n  '),
+          logAdditionalContent && this.additionalContent ?
+            `\n\n${DyFM_Log.errorStyle}AdditionalContent:\n` + this.additionalContent : '' */
+    /**
+     * Checks if the error is parsable,
+     * simplifies the error,
+     * and returns the error as a string.
+     */
+    getParsable() {
+        try {
+            const flat = this.getErrorsFlat();
+            return JSON.stringify(flat);
+        }
+        catch (error) {
+            DyFM_Log.error('Error getting parsable error', error);
+            return JSON.stringify(this.getErrorSimplified());
+        }
+    }
+    static logSimple(message, error) {
+        if (error instanceof DyFM_Error_ControlModel) {
+            error.logSimple(message);
+        }
+        else {
+            DyFM_Log.T_error(message, error);
+        }
+    }
+    static getErrorMessage(error) {
+        return error?._message ??
+            error?.message ??
+            error?.error?._message ??
+            error?.error?.message;
+    }
+    /**
+     * Returns the message of the error.
+     * Returns the userMessage if the message is not set.
+     * (prioritizes the message over the userMessage)
+     */
+    static getAnyMessage(error) {
+        return this.getErrorMessage(error) ?? this.getUserMessage(error);
+    }
+    /**
+     * The USER-FACING message of any caught error: a `DyFM_Error`, a raw `HttpErrorResponse` whose body is a
+     * serialized `DyFM_Error` (`error.error.__userMessage`), or error settings. `undefined` when there is none —
+     * then the caller shows its own business fallback (BFR-CREDIT-041).
+     */
+    static getUserMessage(error) {
+        return error?.__userMessage ??
+            error?.error?.__userMessage ??
+            error?.userMessage;
+    }
+    /**
+     * Returns the user message of the error.
+     * Returns the message if the userMessage is not set.
+     * (prioritizes the userMessage over the message)
+     *
+     * ⚠️ NOT UI-safe as a fallback: without a user message it returns the TECHNICAL message — for a raw
+     * `HttpErrorResponse` that is Angular's `Http failure response for <internal URL>: …`. For a UI use
+     * `DyFM_Error.getUserMessage(error) ?? <business fallback>` (BFR-CREDIT-041).
+     */
+    static getAnyUserMessage(error) {
+        return this.getUserMessage(error) ?? this.getErrorMessage(error);
+    }
+    /**
+     * A hiba szemantikus szöveges változata: saját üzenet + zárójelben a _messages lista első eleme
+     * (gyökér Dynamo Error üzenete), ha van lánc. Nem az object láncon járunk végig, a _messages-t használjuk.
+     */
+    static getSemanticMessage(error) {
+        const ourMessage = this.getErrorMessage(error);
+        if (!this.isDyFMError(error)) {
+            return ourMessage;
+        }
+        const messages = error._messages;
+        const firstMessage = messages && messages.length > 1 ? messages[0] : undefined;
+        if (firstMessage && firstMessage !== ourMessage) {
+            return `${ourMessage} (${firstMessage})`;
+        }
+        return ourMessage;
+    }
+    static getErrorStatus(error) {
+        return error?.___status ??
+            error?.status ??
+            error?.error?.___status ?? 500;
+    }
+    /**
+     * Returns the error code of the error, searching the known shapes in order.
+     *
+     * ⚠️ **At runtime this CAN return `undefined`** — e.g. for a plain `Error` without a `code`
+     * (BFR-CCAPREVISIONED-007). The declared return type is still `string` ONLY for compatibility:
+     * changing it to `string | undefined` breaks strict consumers at compile time (measured
+     * 2026-09-17: 14 definite + 11 probable sites in `ccap-revisioned/server`, `strict: true`).
+     * The type change is staged — until then, ALWAYS apply a fallback (`?? ''` / `?? 'X-CODE'`)
+     * before reading `.length` or other members.
+     */
+    static getErrorCode(error) {
+        return error?._errorCode ??
+            error?.error?._errorCode ??
+            error?.errorCode ??
+            error?.error?.errorCode ??
+            error?.code ??
+            error?.error?.code;
+    }
+    static getErrorStack(error) {
+        return error?.stack ??
+            error?.error?.stack;
+    }
+    static isDyFMError(error) {
+        return error?.flag?.includes('DYNAMO');
+    }
+    /** A plain `{ … }` object (not an array, not a class instance) — the only accepted `publicContext` shape. */
+    static isPlainObject(value) {
+        return typeof value === 'object' && value !== null && !Array.isArray(value)
+            && Object.getPrototypeOf(value) === Object.prototype;
+    }
+    static isAnyDyFMError(error) {
+        return this.isDyFMError(error) ||
+            error?.name === DyFM_httpErrorResponse_name ||
+            error instanceof Error;
+    }
+    static deleteErrorContent(error) {
+        delete error.confidentialContent;
+        delete error.additionalContent;
+        delete error.error;
+        delete error.errors;
+        delete error.stack;
+    }
+    static getStatusText(status) {
+        switch (status) {
+            case 100:
+                return 'Continue';
+            case 101:
+                return 'Switching Protocols';
+            case 102:
+                return 'Processing';
+            case 103:
+                return 'Early Hints';
+            case 200:
+                return 'OK';
+            case 201:
+                return 'Created';
+            case 202:
+                return 'Accepted';
+            case 203:
+                return 'Non-Authoritative Information';
+            case 204:
+                return 'No Content';
+            case 205:
+                return 'Reset Content';
+            case 206:
+                return 'Partial Content';
+            case 207:
+                return 'Multi-Status';
+            case 208:
+                return 'Already Reported';
+            case 226:
+                return 'IM Used';
+            case 300:
+                return 'Multiple Choices';
+            case 301:
+                return 'Moved Permanently';
+            case 302:
+                return 'Found';
+            case 303:
+                return 'See Other';
+            case 304:
+                return 'Not Modified';
+            case 305:
+                return 'Use Proxy';
+            case 306:
+                return 'Switch Proxy';
+            case 307:
+                return 'Temporary Redirect';
+            case 308:
+                return 'Permanent Redirect';
+            case 400:
+                return 'Bad Request';
+            case 401:
+                return 'Unauthorized';
+            case 402:
+                return 'Payment Required';
+            case 403:
+                return 'Forbidden';
+            case 404:
+                return 'Not Found';
+            case 405:
+                return 'Method Not Allowed';
+            case 406:
+                return 'Not Acceptable';
+            case 407:
+                return 'Proxy Authentication Required';
+            case 408:
+                return 'Request Timeout';
+            case 409:
+                return 'Conflict';
+            case 410:
+                return 'Gone';
+            case 411:
+                return 'Length Required';
+            case 412:
+                return 'Precondition Failed';
+            case 413:
+                return 'Payload Too Large';
+            case 414:
+                return 'URI Too Long';
+            case 415:
+                return 'Unsupported Media Type';
+            case 416:
+                return 'Range Not Satisfiable';
+            case 417:
+                return 'Expectation Failed';
+            case 418:
+                return "I'm a teapot";
+            case 421:
+                return 'Misdirected Request';
+            case 422:
+                return 'Unprocessable Entity';
+            case 423:
+                return 'Locked';
+            case 424:
+                return 'Failed Dependency';
+            case 425:
+                return 'Too Early';
+            case 426:
+                return 'Upgrade Required';
+            case 428:
+                return 'Precondition Required';
+            case 429:
+                return 'Too Many Requests';
+            case 431:
+                return 'Request Header Fields Too Large';
+            case 451:
+                return 'Unavailable For Legal Reasons';
+            case 500:
+                return 'Internal Server Error';
+            case 501:
+                return 'Not Implemented';
+            case 502:
+                return 'Bad Gateway';
+            case 503:
+                return 'Service Unavailable';
+            case 504:
+                return 'Gateway Timeout';
+            case 505:
+                return 'HTTP Version Not Supported';
+            case 506:
+                return 'Variant Also Negotiates';
+            case 507:
+                return 'Insufficient Storage';
+            case 508:
+                return 'Loop Detected';
+            case 510:
+                return 'Not Extended';
+            case 511:
+                return 'Network Authentication Required';
+            default:
+                return 'Unknown';
+        }
+    }
+}
+Object.defineProperty(DyFM_Error_ControlModel, 'name', { value: 'DyFM_Error' });
+/** @deprecated Use DyFM_Error_ControlModel. Same constructor; no API removal. */
+export { DyFM_Error_ControlModel as DyFM_Error };
+Object.defineProperty(DyFM_Error_ControlModel.prototype, 'isHandled', {
+    configurable: true,
+    enumerable: false,
+    get: function () {
+        return this.___handled;
+    },
+    set: function (isValue) {
+        this.___handled = isValue;
+    },
+});
+Object.defineProperty(DyFM_Error_ControlModel.prototype, 'isLogged', {
+    configurable: true,
+    enumerable: false,
+    get: function () {
+        return this.___logged;
+    },
+    set: function (isValue) {
+        this.___logged = isValue;
+    },
+});
+Object.defineProperty(DyFM_Error_ControlModel.prototype, 'isLevelUpEnabled', {
+    configurable: true,
+    enumerable: false,
+    get: function () {
+        return this.levelUpThis;
+    },
+    set: function (isValue) {
+        this.levelUpThis = isValue;
+    },
+});