@futdevpro/fsm-dynamo 1.15.14 → 1.15.16

package/build/_collections/utils/extract-error-message.util.d.ts

@@ -0,0 +1,71 @@
+import { DyFM_AnyError } from '../../_models/control-models/error.control-model';
+/**
+ * Options for `DyFM_extractErrorMessage`.
+ */
+export interface DyFM_ExtractErrorMessage_Options {
+    /**
+     * Optional prefix prepended to the result with ': '. e.g. `prefix: 'Login'`
+     * → `'Login: <message>'`. Useful for distinguishing the UI surface.
+     */
+    prefix?: string;
+    /**
+     * Fallback string when no usable message can be extracted. Defaults to
+     * a human-readable diagnostic that mentions checking server logs.
+     */
+    fallback?: string;
+    /**
+     * When `true`, the returned string includes HTTP status + statusText after
+     * the main message (in parens) for HTTP errors. Default: `true`.
+     */
+    includeHttpStatus?: boolean;
+}
+/**
+ * Universal error → human-readable string extractor. **Never** returns the
+ * literal string `'undefined'` (or `'undefined undefined'`), `'[object Object]'`,
+ * or any other JS-rendering artifact. Walks the full DyFM_Error pipeline plus
+ * common Angular HttpErrorResponse + plain Error shapes, falling back to a
+ * meaningful diagnostic string when the input is malformed.
+ *
+ * Order of attempts (first non-empty wins):
+ *   1. `err.__userMessage` (DyFM_Error admin-actionable user message)
+ *   2. `err._message` (DyFM_Error aggregated debug message)
+ *   3. `err.message` (plain Error.message)
+ *   4. `err.userMessage` (deprecated DyFM_Error_Settings field, still seen
+ *      on some payloads)
+ *   5. `err.error.__userMessage` (HttpErrorResponse wrapping a DyFM_Error in
+ *      its body)
+ *   6. `err.error._message`
+ *   7. `err.error.message`
+ *   8. `err.error.userMessage`
+ *   9. If `err` itself is a string, use as-is
+ *  10. JSON-stringified payload (circular-safe; first 200 chars) as a last
+ *      resort, prefixed with 'Malformed error: '
+ *  11. `options.fallback` (or its default)
+ *
+ * When `includeHttpStatus` is true (default) and the input looks like a
+ * HttpErrorResponse, the status + statusText are appended in parens: e.g.
+ * `'Bad credentials (HTTP 401 Unauthorized)'`.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await auth_CS.login(account);
+ * } catch (err) {
+ *   this.formError = DyFM_extractErrorMessage(err, { prefix: 'Login' });
+ *   // → 'Login: Bad credentials (HTTP 401 Unauthorized)'
+ *   //   OR
+ *   // → 'Login: Network unreachable — check connection. Server logs may have detail.'
+ *   //   never 'Login: undefined undefined'
+ * }
+ * ```
+ */
+export declare function DyFM_extractErrorMessage(err: DyFM_AnyError | unknown, options?: DyFM_ExtractErrorMessage_Options): string;
+/**
+ * Convenience: same as DyFM_extractErrorMessage but always includes a default
+ * prefix derived from the calling context, useful for adding diagnostic
+ * breadcrumbs without per-call boilerplate.
+ */
+export declare function DyFM_formatError(err: DyFM_AnyError | unknown, prefix: string): string;
+export declare function DyFM_registerMalformedErrorSink(fn: (err: unknown, context?: string) => void): void;
+export declare function DyFM_reportMalformedError(err: unknown, context?: string): void;
+//# sourceMappingURL=extract-error-message.util.d.ts.map

package/build/_collections/utils/extract-error-message.util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-error-message.util.d.ts","sourceRoot":"","sources":["../../../src/_collections/utils/extract-error-message.util.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAc,MAAM,kDAAkD,CAAC;AAG7F;;GAEG;AACH,MAAM,WAAW,gCAAgC;IAC/C;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAGD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,aAAa,GAAG,OAAO,EAC5B,OAAO,CAAC,EAAE,gCAAgC,GACzC,MAAM,CA2DR;AAqCD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,aAAa,GAAG,OAAO,EAC5B,MAAM,EAAE,MAAM,GACb,MAAM,CAER;AAiBD,wBAAgB,+BAA+B,CAC7C,EAAE,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,GAC3C,IAAI,CAEN;AAED,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,OAAO,EACZ,OAAO,CAAC,EAAE,MAAM,GACf,IAAI,CAoBN"}

package/build/_collections/utils/extract-error-message.util.js

@@ -0,0 +1,186 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DyFM_extractErrorMessage = DyFM_extractErrorMessage;
+exports.DyFM_formatError = DyFM_formatError;
+exports.DyFM_registerMalformedErrorSink = DyFM_registerMalformedErrorSink;
+exports.DyFM_reportMalformedError = DyFM_reportMalformedError;
+/**
+ * Universal error → human-readable string extractor. **Never** returns the
+ * literal string `'undefined'` (or `'undefined undefined'`), `'[object Object]'`,
+ * or any other JS-rendering artifact. Walks the full DyFM_Error pipeline plus
+ * common Angular HttpErrorResponse + plain Error shapes, falling back to a
+ * meaningful diagnostic string when the input is malformed.
+ *
+ * Order of attempts (first non-empty wins):
+ *   1. `err.__userMessage` (DyFM_Error admin-actionable user message)
+ *   2. `err._message` (DyFM_Error aggregated debug message)
+ *   3. `err.message` (plain Error.message)
+ *   4. `err.userMessage` (deprecated DyFM_Error_Settings field, still seen
+ *      on some payloads)
+ *   5. `err.error.__userMessage` (HttpErrorResponse wrapping a DyFM_Error in
+ *      its body)
+ *   6. `err.error._message`
+ *   7. `err.error.message`
+ *   8. `err.error.userMessage`
+ *   9. If `err` itself is a string, use as-is
+ *  10. JSON-stringified payload (circular-safe; first 200 chars) as a last
+ *      resort, prefixed with 'Malformed error: '
+ *  11. `options.fallback` (or its default)
+ *
+ * When `includeHttpStatus` is true (default) and the input looks like a
+ * HttpErrorResponse, the status + statusText are appended in parens: e.g.
+ * `'Bad credentials (HTTP 401 Unauthorized)'`.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await auth_CS.login(account);
+ * } catch (err) {
+ *   this.formError = DyFM_extractErrorMessage(err, { prefix: 'Login' });
+ *   // → 'Login: Bad credentials (HTTP 401 Unauthorized)'
+ *   //   OR
+ *   // → 'Login: Network unreachable — check connection. Server logs may have detail.'
+ *   //   never 'Login: undefined undefined'
+ * }
+ * ```
+ */
+function DyFM_extractErrorMessage(err, options) {
+    const includeHttpStatus = options?.includeHttpStatus !== false;
+    const fallback = options?.fallback
+        ?? 'Unexpected error (no detail in payload — check server logs).';
+    const prefix = options?.prefix ? `${options.prefix}: ` : '';
+    // Null/undefined/empty
+    if (err === null || err === undefined) {
+        return `${prefix}${fallback}`;
+    }
+    // String → use as-is
+    if (typeof err === 'string') {
+        return `${prefix}${err}`;
+    }
+    // Walk the candidate fields in order. Cast to any to access optional
+    // properties without forcing each branch into a separate type guard.
+    const e = err;
+    const innerError = e?.error;
+    const candidate = _nonEmptyString(e?.__userMessage)
+        ?? _nonEmptyString(e?._message)
+        ?? _nonEmptyString(e?.message)
+        ?? _nonEmptyString(e?.userMessage)
+        ?? _nonEmptyString(innerError?.__userMessage)
+        ?? _nonEmptyString(innerError?._message)
+        ?? _nonEmptyString(innerError?.message)
+        ?? _nonEmptyString(innerError?.userMessage);
+    // HTTP status suffix (always-on by default)
+    const status = e?.___status
+        ?? e?.status
+        ?? innerError?.___status
+        ?? innerError?.status;
+    const statusText = _nonEmptyString(e?.statusText)
+        ?? _nonEmptyString(innerError?.statusText);
+    const httpSuffix = (includeHttpStatus && (status !== undefined || statusText !== undefined))
+        ? ` (HTTP ${status ?? '?'}${statusText ? ' ' + statusText : ''})`
+        : '';
+    if (candidate !== undefined) {
+        return `${prefix}${candidate}${httpSuffix}`;
+    }
+    // No usable text field. Try a JSON-stringify of the raw payload (circular-safe).
+    const jsonAttempt = _safeJsonStringify(err);
+    if (jsonAttempt !== undefined && jsonAttempt !== '{}' && jsonAttempt !== '[]') {
+        const trimmed = jsonAttempt.length > 200
+            ? jsonAttempt.slice(0, 200) + '…'
+            : jsonAttempt;
+        return `${prefix}Malformed error: ${trimmed}${httpSuffix}`;
+    }
+    // Total fallback.
+    return `${prefix}${fallback}${httpSuffix}`;
+}
+/**
+ * Returns the value if it's a non-empty string, else undefined.
+ * Trims and treats whitespace-only as empty. Internal helper.
+ */
+function _nonEmptyString(v) {
+    if (typeof v !== 'string') {
+        return undefined;
+    }
+    const trimmed = v.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+/**
+ * JSON.stringify wrapper that survives circular references + non-serializable
+ * values. Returns undefined if even the safe fallback fails (e.g. a Proxy
+ * whose getter throws).
+ */
+function _safeJsonStringify(v) {
+    try {
+        const seen = new WeakSet();
+        return JSON.stringify(v, (_key, value) => {
+            if (typeof value === 'object' && value !== null) {
+                if (seen.has(value)) {
+                    return '[Circular]';
+                }
+                seen.add(value);
+            }
+            if (typeof value === 'function') {
+                return '[Function]';
+            }
+            if (typeof value === 'undefined') {
+                return '[undefined]';
+            }
+            return value;
+        });
+    }
+    catch {
+        try {
+            return String(v);
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+/**
+ * Convenience: same as DyFM_extractErrorMessage but always includes a default
+ * prefix derived from the calling context, useful for adding diagnostic
+ * breadcrumbs without per-call boilerplate.
+ */
+function DyFM_formatError(err, prefix) {
+    return DyFM_extractErrorMessage(err, { prefix: prefix });
+}
+/**
+ * Reports a raw error payload via the universal client-error capture system
+ * (FR-029-style). Implementation is delegated to a consumer-registered
+ * handler so dynamo-fsm stays Angular-agnostic; if no handler is registered
+ * the error is logged via `DyFM_Log.error` (which is the default no-op-safe
+ * sink). Consumers (e.g. A_ErrorHandler_ControlService) call
+ * `DyFM_registerMalformedErrorSink(fn)` once at bootstrap.
+ *
+ * The intent: when DyFM_extractErrorMessage falls back to 'Malformed error:'
+ * or the generic fallback, the raw payload should also be captured for
+ * post-mortem analysis (server error-log via FR-029 pipeline).
+ */
+let _malformedErrorSink;
+function DyFM_registerMalformedErrorSink(fn) {
+    _malformedErrorSink = fn;
+}
+function DyFM_reportMalformedError(err, context) {
+    if (_malformedErrorSink !== undefined) {
+        try {
+            _malformedErrorSink(err, context);
+            return;
+        }
+        catch {
+            /* sink threw — fall through to default */
+        }
+    }
+    // Default: best-effort console.error wrapped in DyFM_Error for stack capture.
+    try {
+        // Lazy require to avoid a hard cycle through error.control-model -> log.util.
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const { DyFM_Log } = require('./log.util');
+        DyFM_Log.error(`[DyFM_reportMalformedError] ${context ?? 'unknown context'}`, err);
+    }
+    catch {
+        // Last-ditch — should never happen since log.util has no further deps.
+        /* swallow */
+    }
+}
+//# sourceMappingURL=extract-error-message.util.js.map

package/build/_collections/utils/extract-error-message.util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-error-message.util.js","sourceRoot":"","sources":["../../../src/_collections/utils/extract-error-message.util.ts"],"names":[],"mappings":"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"}

package/build/_collections/utils/require-env.util.d.ts

@@ -5,7 +5,7 @@ export interface DyFM_RequireEnv_Options {
     /**
      * Stable error code emitted on the DyFM_Error when the env-var is missing
      * and no fallback is configured. Convention: `<PACKAGE>-ENV-MISSING-<KEY>`,
-     * e.g. `DyNM-ENV-MISSING-STORAGE-KEY`, `FDP-ENV-MISSING-AUTH-KEY`.
+     * e.g. `DyNM-ENV-MISSING-STORAGE-KEY`, `FDP-ENV-MISSING-CORE-FE-AUTH-KEY`.
      */
     errorCode: string;
     /**
@@ -60,8 +60,8 @@ export interface DyFM_RequireEnv_Options {
  * import { DyFM_requireEnv } from '@futdevpro/fsm-dynamo';
  *
  * export const FDP_keysEnv_settingsBase = {
- *   authKey: DyFM_requireEnv('FDP_AUTH_KEY', {
- *     errorCode: 'FDP-ENV-MISSING-AUTH-KEY',
+ *   authKey: DyFM_requireEnv('FDP_CORE_FE_AUTH_KEY', {
+ *     errorCode: 'FDP-ENV-MISSING-CORE-FE-AUTH-KEY',
  *     issuerService: 'fdp-templates',
  *     fallback: '<inherit literal>',   // remove for Wave 3
  *   }),

package/build/_collections/utils/require-env.util.js

@@ -33,8 +33,8 @@ const global_settings_const_1 = require("../constants/global-settings.const");
  * import { DyFM_requireEnv } from '@futdevpro/fsm-dynamo';
  *
  * export const FDP_keysEnv_settingsBase = {
- *   authKey: DyFM_requireEnv('FDP_AUTH_KEY', {
- *     errorCode: 'FDP-ENV-MISSING-AUTH-KEY',
+ *   authKey: DyFM_requireEnv('FDP_CORE_FE_AUTH_KEY', {
+ *     errorCode: 'FDP-ENV-MISSING-CORE-FE-AUTH-KEY',
  *     issuerService: 'fdp-templates',
  *     fallback: '<inherit literal>',   // remove for Wave 3
  *   }),

package/build/_models/interfaces/environment/global-settings.interface.d.ts

@@ -29,7 +29,7 @@ export interface DyFM_Global_Settings {
      * import { environment } from './environments/environment';
      *
      * DyFM_global_settings.envOverrides = {
-     *   FDP_AUTH_KEY: environment.authKey,
+     *   FDP_CORE_FE_AUTH_KEY: environment.authKey,
      *   FDP_EXTRA_AUTH_STORAGE_KEY: environment.extraAuthStorageKey,
      *   DyNM_STORAGE_ENCRYPTION_KEY: environment.storageEncryptionKey,
      * };

package/build/index.d.ts

@@ -6,6 +6,7 @@ export * from './_collections/constants/times.const';
 export * from './_collections/utils/array.util';
 export * from './_collections/utils/async.util';
 export * from './_collections/utils/data.util';
+export * from './_collections/utils/extract-error-message.util';
 export * from './_collections/utils/json-error-helper.util';
 export * from './_collections/utils/log.util';
 export * from './_collections/utils/round-list.util';

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,2CAA2C,CAAC;AAC1D,cAAc,+CAA+C,CAAC;AAC9D,cAAc,gDAAgD,CAAC;AAC/D,cAAc,wCAAwC,CAAC;AACvD,cAAc,sCAAsC,CAAC;AAGrD,cAAc,iCAAiC,CAAC;AAChD,cAAc,iCAAiC,CAAC;AAChD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6CAA6C,CAAC;AAC5D,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sCAAsC,CAAC;AACrD,cAAc,kCAAkC,CAAC;AACjD,cAAc,uCAAuC,CAAC;AACtD,cAAc,iCAAiC,CAAC;AAChD,cAAc,kCAAkC,CAAC;AACjD,cAAc,uCAAuC,CAAC;AACtD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,iDAAiD,CAAC;AAChE,cAAc,qCAAqC,CAAC;AACpD,cAAc,gCAAgC,CAAC;AAG/C,cAAc,2CAA2C,CAAC;AAC1D,cAAc,qCAAqC,CAAC;AACpD,cAAc,uCAAuC,CAAC;AACtD,cAAc,6CAA6C,CAAC;AAC5D,cAAc,wCAAwC,CAAC;AAGvD,cAAc,gDAAgD,CAAC;AAC/D,cAAc,uCAAuC,CAAC;AACtD,cAAc,gDAAgD,CAAC;AAI/D,cAAc,mCAAmC,CAAC;AAClD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,wCAAwC,CAAC;AAGvD,cAAc,mCAAmC,CAAC;AAClD,cAAc,oCAAoC,CAAC;AACnD,cAAc,uCAAuC,CAAC;AAGtD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,0BAA0B,CAAC;AACzC,cAAc,kCAAkC,CAAC;AAKjD,cAAc,0DAA0D,CAAC;AACzE,cAAc,6DAA6D,CAAC;AAC5E,cAAc,8CAA8C,CAAC;AAC7D,cAAc,6CAA6C,CAAC;AAC5D,cAAc,oDAAoD,CAAC;AACnE,cAAc,sDAAsD,CAAC;AACrE,cAAc,uEAAuE,CAAC;AAGtF,cAAc,iEAAiE,CAAC;AAChF,cAAc,0DAA0D,CAAC;AACzE,cAAc,wDAAwD,CAAC;AAGvE,cAAc,yCAAyC,CAAC;AACxD,cAAc,2CAA2C,CAAC;AAG1D,cAAc,2CAA2C,CAAC;AAC1D,cAAc,+CAA+C,CAAC;AAC9D,cAAc,sCAAsC,CAAC;AACrD,cAAc,8CAA8C,CAAC;AAC7D,cAAc,+CAA+C,CAAC;AAC9D,cAAc,6CAA6C,CAAC;AAC5D,cAAc,8CAA8C,CAAC;AAC7D,cAAc,wDAAwD,CAAC;AACvE,cAAc,wCAAwC,CAAC;AAGvD,cAAc,gEAAgE,CAAC;AAC/E,cAAc,4DAA4D,CAAC;AAG3E,cAAc,gCAAgC,CAAC;AAC/C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,8BAA8B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,2CAA2C,CAAC;AAC1D,cAAc,+CAA+C,CAAC;AAC9D,cAAc,gDAAgD,CAAC;AAC/D,cAAc,wCAAwC,CAAC;AACvD,cAAc,sCAAsC,CAAC;AAGrD,cAAc,iCAAiC,CAAC;AAChD,cAAc,iCAAiC,CAAC;AAChD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,iDAAiD,CAAC;AAChE,cAAc,6CAA6C,CAAC;AAC5D,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sCAAsC,CAAC;AACrD,cAAc,kCAAkC,CAAC;AACjD,cAAc,uCAAuC,CAAC;AACtD,cAAc,iCAAiC,CAAC;AAChD,cAAc,kCAAkC,CAAC;AACjD,cAAc,uCAAuC,CAAC;AACtD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,iDAAiD,CAAC;AAChE,cAAc,qCAAqC,CAAC;AACpD,cAAc,gCAAgC,CAAC;AAG/C,cAAc,2CAA2C,CAAC;AAC1D,cAAc,qCAAqC,CAAC;AACpD,cAAc,uCAAuC,CAAC;AACtD,cAAc,6CAA6C,CAAC;AAC5D,cAAc,wCAAwC,CAAC;AAGvD,cAAc,gDAAgD,CAAC;AAC/D,cAAc,uCAAuC,CAAC;AACtD,cAAc,gDAAgD,CAAC;AAI/D,cAAc,mCAAmC,CAAC;AAClD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,wCAAwC,CAAC;AAGvD,cAAc,mCAAmC,CAAC;AAClD,cAAc,oCAAoC,CAAC;AACnD,cAAc,uCAAuC,CAAC;AAGtD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,0BAA0B,CAAC;AACzC,cAAc,kCAAkC,CAAC;AAKjD,cAAc,0DAA0D,CAAC;AACzE,cAAc,6DAA6D,CAAC;AAC5E,cAAc,8CAA8C,CAAC;AAC7D,cAAc,6CAA6C,CAAC;AAC5D,cAAc,oDAAoD,CAAC;AACnE,cAAc,sDAAsD,CAAC;AACrE,cAAc,uEAAuE,CAAC;AAGtF,cAAc,iEAAiE,CAAC;AAChF,cAAc,0DAA0D,CAAC;AACzE,cAAc,wDAAwD,CAAC;AAGvE,cAAc,yCAAyC,CAAC;AACxD,cAAc,2CAA2C,CAAC;AAG1D,cAAc,2CAA2C,CAAC;AAC1D,cAAc,+CAA+C,CAAC;AAC9D,cAAc,sCAAsC,CAAC;AACrD,cAAc,8CAA8C,CAAC;AAC7D,cAAc,+CAA+C,CAAC;AAC9D,cAAc,6CAA6C,CAAC;AAC5D,cAAc,8CAA8C,CAAC;AAC7D,cAAc,wDAAwD,CAAC;AACvE,cAAc,wCAAwC,CAAC;AAGvD,cAAc,gEAAgE,CAAC;AAC/E,cAAc,4DAA4D,CAAC;AAG3E,cAAc,gCAAgC,CAAC;AAC/C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,8BAA8B,CAAC"}

package/build/index.js

@@ -12,6 +12,7 @@ tslib_1.__exportStar(require("./_collections/constants/times.const"), exports);
 tslib_1.__exportStar(require("./_collections/utils/array.util"), exports);
 tslib_1.__exportStar(require("./_collections/utils/async.util"), exports);
 tslib_1.__exportStar(require("./_collections/utils/data.util"), exports);
+tslib_1.__exportStar(require("./_collections/utils/extract-error-message.util"), exports);
 tslib_1.__exportStar(require("./_collections/utils/json-error-helper.util"), exports);
 tslib_1.__exportStar(require("./_collections/utils/log.util"), exports);
 tslib_1.__exportStar(require("./_collections/utils/round-list.util"), exports);

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AACA,cAAc;AACd,wBAAwB;AACxB,oFAA0D;AAC1D,wFAA8D;AAC9D,yFAA+D;AAC/D,iFAAuD;AACvD,+EAAqD;AAErD,oBAAoB;AACpB,0EAAgD;AAChD,0EAAgD;AAChD,yEAA+C;AAC/C,sFAA4D;AAC5D,wEAA8C;AAC9C,+EAAqD;AACrD,2EAAiD;AACjD,gFAAsD;AACtD,0EAAgD;AAChD,2EAAiD;AACjD,gFAAsD;AACtD,yEAA+C;AAC/C,0FAAgE;AAChE,8EAAoD;AACpD,yEAA+C;AAE/C,yBAAyB;AACzB,oFAA0D;AAC1D,8EAAoD;AACpD,gFAAsD;AACtD,sFAA4D;AAC5D,iFAAuD;AAEvD,2BAA2B;AAC3B,yFAA+D;AAC/D,gFAAsD;AACtD,yFAA+D;AAG/D,QAAQ;AACR,4EAAkD;AAClD,wEAA8C;AAC9C,yEAA+C;AAC/C,oEAA0C;AAC1C,kEAAwC;AACxC,iFAAuD;AAEvD,aAAa;AACb,4EAAkD;AAClD,6EAAmD;AACnD,gFAAsD;AAEtD,aAAa;AACb,yEAA+C;AAC/C,mEAAyC;AACzC,2EAAiD;AAGjD,SAAS;AACT,wBAAwB;AACxB,mGAAyE;AACzE,sGAA4E;AAC5E,uFAA6D;AAC7D,sFAA4D;AAC5D,6FAAmE;AACnE,+FAAqE;AACrE,gHAAsF;AAEtF,6BAA6B;AAC7B,0GAAgF;AAChF,mGAAyE;AACzE,iGAAuE;AAEvE,qBAAqB;AACrB,kFAAwD;AACxD,oFAA0D;AAE1D,oBAAoB;AACpB,oFAA0D;AAC1D,wFAA8D;AAC9D,+EAAqD;AACrD,uFAA6D;AAC7D,wFAA8D;AAC9D,sFAA4D;AAC5D,uFAA6D;AAC7D,iGAAuE;AACvE,iFAAuD;AAEvD,gCAAgC;AAChC,yGAA+E;AAC/E,qGAA2E;AAE3E,eAAe;AACf,yEAA+C;AAC/C,uEAA6C;AAC7C,yEAA+C;AAC/C,uEAA6C"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AACA,cAAc;AACd,wBAAwB;AACxB,oFAA0D;AAC1D,wFAA8D;AAC9D,yFAA+D;AAC/D,iFAAuD;AACvD,+EAAqD;AAErD,oBAAoB;AACpB,0EAAgD;AAChD,0EAAgD;AAChD,yEAA+C;AAC/C,0FAAgE;AAChE,sFAA4D;AAC5D,wEAA8C;AAC9C,+EAAqD;AACrD,2EAAiD;AACjD,gFAAsD;AACtD,0EAAgD;AAChD,2EAAiD;AACjD,gFAAsD;AACtD,yEAA+C;AAC/C,0FAAgE;AAChE,8EAAoD;AACpD,yEAA+C;AAE/C,yBAAyB;AACzB,oFAA0D;AAC1D,8EAAoD;AACpD,gFAAsD;AACtD,sFAA4D;AAC5D,iFAAuD;AAEvD,2BAA2B;AAC3B,yFAA+D;AAC/D,gFAAsD;AACtD,yFAA+D;AAG/D,QAAQ;AACR,4EAAkD;AAClD,wEAA8C;AAC9C,yEAA+C;AAC/C,oEAA0C;AAC1C,kEAAwC;AACxC,iFAAuD;AAEvD,aAAa;AACb,4EAAkD;AAClD,6EAAmD;AACnD,gFAAsD;AAEtD,aAAa;AACb,yEAA+C;AAC/C,mEAAyC;AACzC,2EAAiD;AAGjD,SAAS;AACT,wBAAwB;AACxB,mGAAyE;AACzE,sGAA4E;AAC5E,uFAA6D;AAC7D,sFAA4D;AAC5D,6FAAmE;AACnE,+FAAqE;AACrE,gHAAsF;AAEtF,6BAA6B;AAC7B,0GAAgF;AAChF,mGAAyE;AACzE,iGAAuE;AAEvE,qBAAqB;AACrB,kFAAwD;AACxD,oFAA0D;AAE1D,oBAAoB;AACpB,oFAA0D;AAC1D,wFAA8D;AAC9D,+EAAqD;AACrD,uFAA6D;AAC7D,wFAA8D;AAC9D,sFAA4D;AAC5D,uFAA6D;AAC7D,iGAAuE;AACvE,iFAAuD;AAEvD,gCAAgC;AAChC,yGAA+E;AAC/E,qGAA2E;AAE3E,eAAe;AACf,yEAA+C;AAC/C,uEAA6C;AAC7C,yEAA+C;AAC/C,uEAA6C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@futdevpro/fsm-dynamo",
-  "version": "01.15.14",
+  "version": "01.15.16",
   "description": "Full Stack Model Collection for Dynamic (NodeJS-Typescript) Framework called Dynamo, by Future Development Ltd.",
   "DyBu_settings": {
     "packageType": "full-stack-package",

package/src/_collections/utils/extract-error-message.util.spec.ts

@@ -0,0 +1,204 @@
+import { DyFM_Error } from '../../_models/control-models/error.control-model';
+import {
+  DyFM_extractErrorMessage,
+  DyFM_formatError,
+  DyFM_registerMalformedErrorSink,
+  DyFM_reportMalformedError,
+} from './extract-error-message.util';
+
+
+/**
+ * FR-015-P0-fix — DyFM_extractErrorMessage specs.
+ *
+ * Coverage:
+ *   - DyFM_Error with __userMessage / _message / both
+ *   - HttpErrorResponse-shaped (status + statusText + error body)
+ *   - Plain Error.message
+ *   - String input
+ *   - null / undefined → fallback (never 'undefined undefined')
+ *   - Empty object → 'Malformed error: {}' OR fallback (depending on json)
+ *   - Circular reference handled (no infinite loop / no crash)
+ *   - prefix option
+ *   - includeHttpStatus toggle
+ *   - DyFM_formatError convenience wrapper
+ *   - DyFM_reportMalformedError sink registration
+ *
+ * MUST never emit:
+ *   - literal 'undefined' anywhere in the returned string
+ *   - '[object Object]'
+ *   - bare empty string
+ */
+describe('| DyFM_extractErrorMessage', (): void => {
+
+  describe('| DyFM_Error inputs', (): void => {
+    it('| uses __userMessage when present', (): void => {
+      const err: DyFM_Error = new DyFM_Error({
+        status: 401,
+        message: 'Internal debug',
+        userMessage: 'Bad credentials',
+        errorCode: 'AUTH-001',
+      });
+      // userMessage from settings maps to __userMessage on the DyFM_Error instance
+      // (deprecated but still copied).
+      const result: string = DyFM_extractErrorMessage(err);
+      expect(result).toContain('Bad credentials');
+      expect(result).not.toContain('undefined');
+    });
+
+    it('| falls back to _message when no __userMessage', (): void => {
+      const err: DyFM_Error = new DyFM_Error({
+        status: 500,
+        message: 'Database connection lost',
+        errorCode: 'DB-001',
+      });
+      const result: string = DyFM_extractErrorMessage(err);
+      expect(result).toContain('Database connection lost');
+      expect(result).not.toContain('undefined');
+    });
+
+    it('| appends HTTP status when present', (): void => {
+      const err: DyFM_Error = new DyFM_Error({
+        status: 401,
+        message: 'Token expired',
+        errorCode: 'AUTH-002',
+      });
+      const result: string = DyFM_extractErrorMessage(err);
+      expect(result).toContain('Token expired');
+      expect(result).toContain('401');
+    });
+  });
+
+  describe('| HttpErrorResponse-shaped inputs', (): void => {
+    it('| extracts from nested .error.__userMessage', (): void => {
+      const httpErr: object = {
+        status: 401,
+        statusText: 'Unauthorized',
+        error: {
+          __userMessage: 'Invalid username or password',
+          _errorCode: 'FAS-ACS-LOG1',
+        },
+      };
+      const result: string = DyFM_extractErrorMessage(httpErr);
+      expect(result).toContain('Invalid username or password');
+      expect(result).toContain('401');
+      expect(result).toContain('Unauthorized');
+      expect(result).not.toContain('undefined');
+    });
+
+    it('| extracts from nested .error.message (no DyFM extras)', (): void => {
+      const httpErr: object = {
+        status: 500,
+        statusText: 'Internal Server Error',
+        error: { message: 'ECONNREFUSED' },
+      };
+      const result: string = DyFM_extractErrorMessage(httpErr);
+      expect(result).toContain('ECONNREFUSED');
+      expect(result).toContain('500');
+      expect(result).not.toContain('undefined');
+    });
+
+    it('| status without statusText still rendered cleanly', (): void => {
+      const httpErr: object = {
+        status: 502,
+        error: { __userMessage: 'Upstream down' },
+      };
+      const result: string = DyFM_extractErrorMessage(httpErr);
+      expect(result).toContain('Upstream down');
+      expect(result).toContain('502');
+      expect(result).not.toContain('undefined');
+    });
+  });
+
+  describe('| primitive + edge inputs (the "undefined undefined" guard)', (): void => {
+    it('| null → fallback, never literal "undefined"', (): void => {
+      const result: string = DyFM_extractErrorMessage(null);
+      expect(result).not.toContain('undefined');
+      expect(result.length).toBeGreaterThan(0);
+    });
+
+    it('| undefined → fallback', (): void => {
+      const result: string = DyFM_extractErrorMessage(undefined);
+      expect(result).not.toContain('undefined');
+      expect(result.length).toBeGreaterThan(0);
+    });
+
+    it('| string input returned as-is', (): void => {
+      const result: string = DyFM_extractErrorMessage('Network unreachable');
+      expect(result).toBe('Network unreachable');
+    });
+
+    it('| plain Error.message', (): void => {
+      const result: string = DyFM_extractErrorMessage(new Error('boom'));
+      expect(result).toContain('boom');
+      expect(result).not.toContain('undefined');
+    });
+
+    it('| empty object → "Malformed error: {}" or fallback, NEVER bare undefined', (): void => {
+      const result: string = DyFM_extractErrorMessage({});
+      expect(result.length).toBeGreaterThan(0);
+      expect(result).not.toContain('undefined undefined');
+      // Either Malformed-error report or fallback — both are acceptable.
+    });
+
+    it('| HttpErrorResponse with ALL undefined fields → fallback, never literal "undefined undefined"', (): void => {
+      // This is the EXACT shape that produced the bug today:
+      // errorRes?.status, errorRes?.error?.status, errorRes?.statusText,
+      // errorRes?.error?.statusText all undefined.
+      const httpErr: object = { error: {} };
+      const result: string = DyFM_extractErrorMessage(httpErr, { prefix: 'Login' });
+      expect(result.startsWith('Login:')).toBeTrue();
+      expect(result).not.toContain('undefined');
+      expect(result).not.toContain('[object Object]');
+    });
+  });
+
+  describe('| circular reference safety', (): void => {
+    it('| does not crash + does not loop', (): void => {
+      const a: { name: string; self?: object } = { name: 'a' };
+      a.self = a;
+      const result: string = DyFM_extractErrorMessage(a);
+      expect(result.length).toBeGreaterThan(0);
+      expect(result).not.toContain('undefined');
+    });
+  });
+
+  describe('| prefix + includeHttpStatus options', (): void => {
+    it('| prefix prepends with ": "', (): void => {
+      const result: string = DyFM_extractErrorMessage('boom', { prefix: 'Login' });
+      expect(result).toBe('Login: boom');
+    });
+
+    it('| includeHttpStatus=false skips the (HTTP …) suffix', (): void => {
+      const httpErr: object = { status: 500, statusText: 'X', error: { message: 'm' } };
+      const result: string = DyFM_extractErrorMessage(httpErr, { includeHttpStatus: false });
+      expect(result).toContain('m');
+      expect(result).not.toContain('HTTP');
+    });
+
+    it('| custom fallback honored', (): void => {
+      const result: string = DyFM_extractErrorMessage(null, { fallback: 'Custom retry message' });
+      expect(result).toContain('Custom retry message');
+    });
+  });
+
+  describe('| DyFM_formatError convenience wrapper', (): void => {
+    it('| applies prefix', (): void => {
+      const result: string = DyFM_formatError('boom', 'Register');
+      expect(result).toBe('Register: boom');
+    });
+  });
+
+  describe('| DyFM_reportMalformedError sink', (): void => {
+    it('| calls registered sink with err + context', (): void => {
+      const calls: Array<{ err: unknown; context?: string }> = [];
+      DyFM_registerMalformedErrorSink((err: unknown, context?: string): void => {
+        calls.push({ err: err, context: context });
+      });
+      DyFM_reportMalformedError({ weirdShape: true }, 'login-flow');
+      expect(calls.length).toBe(1);
+      expect(calls[0].context).toBe('login-flow');
+      // Reset sink (no public unregister; pass an explicit no-op for cleanup).
+      DyFM_registerMalformedErrorSink((): void => { /* no-op */ });
+    });
+  });
+});

package/src/_collections/utils/extract-error-message.util.ts

@@ -0,0 +1,223 @@
+import { DyFM_AnyError, DyFM_Error } from '../../_models/control-models/error.control-model';
+
+
+/**
+ * Options for `DyFM_extractErrorMessage`.
+ */
+export interface DyFM_ExtractErrorMessage_Options {
+  /**
+   * Optional prefix prepended to the result with ': '. e.g. `prefix: 'Login'`
+   * → `'Login: <message>'`. Useful for distinguishing the UI surface.
+   */
+  prefix?: string;
+
+  /**
+   * Fallback string when no usable message can be extracted. Defaults to
+   * a human-readable diagnostic that mentions checking server logs.
+   */
+  fallback?: string;
+
+  /**
+   * When `true`, the returned string includes HTTP status + statusText after
+   * the main message (in parens) for HTTP errors. Default: `true`.
+   */
+  includeHttpStatus?: boolean;
+}
+
+
+/**
+ * Universal error → human-readable string extractor. **Never** returns the
+ * literal string `'undefined'` (or `'undefined undefined'`), `'[object Object]'`,
+ * or any other JS-rendering artifact. Walks the full DyFM_Error pipeline plus
+ * common Angular HttpErrorResponse + plain Error shapes, falling back to a
+ * meaningful diagnostic string when the input is malformed.
+ *
+ * Order of attempts (first non-empty wins):
+ *   1. `err.__userMessage` (DyFM_Error admin-actionable user message)
+ *   2. `err._message` (DyFM_Error aggregated debug message)
+ *   3. `err.message` (plain Error.message)
+ *   4. `err.userMessage` (deprecated DyFM_Error_Settings field, still seen
+ *      on some payloads)
+ *   5. `err.error.__userMessage` (HttpErrorResponse wrapping a DyFM_Error in
+ *      its body)
+ *   6. `err.error._message`
+ *   7. `err.error.message`
+ *   8. `err.error.userMessage`
+ *   9. If `err` itself is a string, use as-is
+ *  10. JSON-stringified payload (circular-safe; first 200 chars) as a last
+ *      resort, prefixed with 'Malformed error: '
+ *  11. `options.fallback` (or its default)
+ *
+ * When `includeHttpStatus` is true (default) and the input looks like a
+ * HttpErrorResponse, the status + statusText are appended in parens: e.g.
+ * `'Bad credentials (HTTP 401 Unauthorized)'`.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await auth_CS.login(account);
+ * } catch (err) {
+ *   this.formError = DyFM_extractErrorMessage(err, { prefix: 'Login' });
+ *   // → 'Login: Bad credentials (HTTP 401 Unauthorized)'
+ *   //   OR
+ *   // → 'Login: Network unreachable — check connection. Server logs may have detail.'
+ *   //   never 'Login: undefined undefined'
+ * }
+ * ```
+ */
+export function DyFM_extractErrorMessage(
+  err: DyFM_AnyError | unknown,
+  options?: DyFM_ExtractErrorMessage_Options,
+): string {
+  const includeHttpStatus: boolean = options?.includeHttpStatus !== false;
+  const fallback: string = options?.fallback
+    ?? 'Unexpected error (no detail in payload — check server logs).';
+  const prefix: string = options?.prefix ? `${options.prefix}: ` : '';
+
+  // Null/undefined/empty
+  if (err === null || err === undefined) {
+    return `${prefix}${fallback}`;
+  }
+
+  // String → use as-is
+  if (typeof err === 'string') {
+    return `${prefix}${err}`;
+  }
+
+  // Walk the candidate fields in order. Cast to any to access optional
+  // properties without forcing each branch into a separate type guard.
+  const e: any = err as any;
+  const innerError: any = e?.error;
+
+  const candidate: string | undefined =
+       _nonEmptyString(e?.__userMessage)
+    ?? _nonEmptyString(e?._message)
+    ?? _nonEmptyString(e?.message)
+    ?? _nonEmptyString(e?.userMessage)
+    ?? _nonEmptyString(innerError?.__userMessage)
+    ?? _nonEmptyString(innerError?._message)
+    ?? _nonEmptyString(innerError?.message)
+    ?? _nonEmptyString(innerError?.userMessage);
+
+  // HTTP status suffix (always-on by default)
+  const status: number | string | undefined =
+       e?.___status
+    ?? e?.status
+    ?? innerError?.___status
+    ?? innerError?.status;
+  const statusText: string | undefined =
+       _nonEmptyString(e?.statusText)
+    ?? _nonEmptyString(innerError?.statusText);
+  const httpSuffix: string = (includeHttpStatus && (status !== undefined || statusText !== undefined))
+    ? ` (HTTP ${status ?? '?'}${statusText ? ' ' + statusText : ''})`
+    : '';
+
+  if (candidate !== undefined) {
+    return `${prefix}${candidate}${httpSuffix}`;
+  }
+
+  // No usable text field. Try a JSON-stringify of the raw payload (circular-safe).
+  const jsonAttempt: string | undefined = _safeJsonStringify(err);
+  if (jsonAttempt !== undefined && jsonAttempt !== '{}' && jsonAttempt !== '[]') {
+    const trimmed: string = jsonAttempt.length > 200
+      ? jsonAttempt.slice(0, 200) + '…'
+      : jsonAttempt;
+    return `${prefix}Malformed error: ${trimmed}${httpSuffix}`;
+  }
+
+  // Total fallback.
+  return `${prefix}${fallback}${httpSuffix}`;
+}
+
+
+/**
+ * Returns the value if it's a non-empty string, else undefined.
+ * Trims and treats whitespace-only as empty. Internal helper.
+ */
+function _nonEmptyString(v: unknown): string | undefined {
+  if (typeof v !== 'string') { return undefined; }
+  const trimmed: string = v.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+
+/**
+ * JSON.stringify wrapper that survives circular references + non-serializable
+ * values. Returns undefined if even the safe fallback fails (e.g. a Proxy
+ * whose getter throws).
+ */
+function _safeJsonStringify(v: unknown): string | undefined {
+  try {
+    const seen: WeakSet<object> = new WeakSet<object>();
+    return JSON.stringify(v, (_key: string, value: unknown): unknown => {
+      if (typeof value === 'object' && value !== null) {
+        if (seen.has(value as object)) { return '[Circular]'; }
+        seen.add(value as object);
+      }
+      if (typeof value === 'function') { return '[Function]'; }
+      if (typeof value === 'undefined') { return '[undefined]'; }
+      return value;
+    });
+  } catch {
+    try { return String(v); } catch { return undefined; }
+  }
+}
+
+
+/**
+ * Convenience: same as DyFM_extractErrorMessage but always includes a default
+ * prefix derived from the calling context, useful for adding diagnostic
+ * breadcrumbs without per-call boilerplate.
+ */
+export function DyFM_formatError(
+  err: DyFM_AnyError | unknown,
+  prefix: string,
+): string {
+  return DyFM_extractErrorMessage(err, { prefix: prefix });
+}
+
+
+/**
+ * Reports a raw error payload via the universal client-error capture system
+ * (FR-029-style). Implementation is delegated to a consumer-registered
+ * handler so dynamo-fsm stays Angular-agnostic; if no handler is registered
+ * the error is logged via `DyFM_Log.error` (which is the default no-op-safe
+ * sink). Consumers (e.g. A_ErrorHandler_ControlService) call
+ * `DyFM_registerMalformedErrorSink(fn)` once at bootstrap.
+ *
+ * The intent: when DyFM_extractErrorMessage falls back to 'Malformed error:'
+ * or the generic fallback, the raw payload should also be captured for
+ * post-mortem analysis (server error-log via FR-029 pipeline).
+ */
+let _malformedErrorSink: ((err: unknown, context?: string) => void) | undefined;
+
+export function DyFM_registerMalformedErrorSink(
+  fn: (err: unknown, context?: string) => void,
+): void {
+  _malformedErrorSink = fn;
+}
+
+export function DyFM_reportMalformedError(
+  err: unknown,
+  context?: string,
+): void {
+  if (_malformedErrorSink !== undefined) {
+    try {
+      _malformedErrorSink(err, context);
+      return;
+    } catch {
+      /* sink threw — fall through to default */
+    }
+  }
+  // Default: best-effort console.error wrapped in DyFM_Error for stack capture.
+  try {
+    // Lazy require to avoid a hard cycle through error.control-model -> log.util.
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { DyFM_Log }: { DyFM_Log: { error(msg: string, ...args: unknown[]): void } } =
+      require('./log.util');
+    DyFM_Log.error(`[DyFM_reportMalformedError] ${context ?? 'unknown context'}`, err);
+  } catch {
+    // Last-ditch — should never happen since log.util has no further deps.
+    /* swallow */
+  }
+}

package/src/_collections/utils/require-env.util.ts

@@ -9,7 +9,7 @@ export interface DyFM_RequireEnv_Options {
   /**
    * Stable error code emitted on the DyFM_Error when the env-var is missing
    * and no fallback is configured. Convention: `<PACKAGE>-ENV-MISSING-<KEY>`,
-   * e.g. `DyNM-ENV-MISSING-STORAGE-KEY`, `FDP-ENV-MISSING-AUTH-KEY`.
+   * e.g. `DyNM-ENV-MISSING-STORAGE-KEY`, `FDP-ENV-MISSING-CORE-FE-AUTH-KEY`.
    */
   errorCode: string;
 
@@ -69,8 +69,8 @@ export interface DyFM_RequireEnv_Options {
  * import { DyFM_requireEnv } from '@futdevpro/fsm-dynamo';
  *
  * export const FDP_keysEnv_settingsBase = {
- *   authKey: DyFM_requireEnv('FDP_AUTH_KEY', {
- *     errorCode: 'FDP-ENV-MISSING-AUTH-KEY',
+ *   authKey: DyFM_requireEnv('FDP_CORE_FE_AUTH_KEY', {
+ *     errorCode: 'FDP-ENV-MISSING-CORE-FE-AUTH-KEY',
  *     issuerService: 'fdp-templates',
  *     fallback: '<inherit literal>',   // remove for Wave 3
  *   }),

package/src/_models/interfaces/environment/global-settings.interface.ts

@@ -34,7 +34,7 @@ export interface DyFM_Global_Settings {
    * import { environment } from './environments/environment';
    *
    * DyFM_global_settings.envOverrides = {
-   *   FDP_AUTH_KEY: environment.authKey,
+   *   FDP_CORE_FE_AUTH_KEY: environment.authKey,
    *   FDP_EXTRA_AUTH_STORAGE_KEY: environment.extraAuthStorageKey,
    *   DyNM_STORAGE_ENCRYPTION_KEY: environment.storageEncryptionKey,
    * };

package/src/index.ts

@@ -11,6 +11,7 @@ export * from './_collections/constants/times.const';
 export * from './_collections/utils/array.util';
 export * from './_collections/utils/async.util';
 export * from './_collections/utils/data.util';
+export * from './_collections/utils/extract-error-message.util';
 export * from './_collections/utils/json-error-helper.util';
 export * from './_collections/utils/log.util';
 export * from './_collections/utils/round-list.util';