@futdevpro/fsm-dynamo 1.16.38 → 1.16.39

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

@@ -1,223 +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 */
-  }
-}
+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 */
+  }
+}