@futdevpro/fsm-dynamo 1.16.39 → 1.20.2

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

@@ -1,186 +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 */
-    }
-}
+"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/json-error-helper.util.d.ts

@@ -1,101 +1,101 @@
-/**
- * JSON Error Handling Helper Utilities
- * Provides enhanced error handling for JSON parsing operations
- *
- * @author FutDevPro
- * @version 1.0.0
- */
-/**
- * Interface for line information extracted from JSON parsing errors
- */
-export interface JsonErrorLineInfo {
-    /** The line number where the error occurred */
-    lineNumber: number;
-    /** Array of context lines around the error (typically ±5 lines) */
-    contextLines: string[];
-    /** The character position within the line where the error occurred */
-    characterPosition: number;
-}
-/**
- * Helper class for JSON error handling and enhanced parsing
- */
-export declare class DyFM_JsonErrorHelper {
-    /**
-     * Extracts line information from JSON parsing error messages
-     * Parses error messages like "Expected property name or '}' in JSON at position 10"
-     * and returns the problematic line with surrounding context
-     *
-     * @param errorMessage - The JSON parsing error message
-     * @param jsonInput - The original JSON input string
-     * @param contextLines - Number of context lines to show before and after the error (default: 5)
-     * @returns Object containing line number, context lines, and character position, or null if parsing fails
-     *
-     * @example
-     * ```ts
-     * const lineInfo = DyFM_JsonErrorHelper.extractLineInfoFromJsonError('Expected property name or "}" in JSON at position 10', '{"name": "John", "age": 30}', 5);
-     * console.log(lineInfo); // { lineNumber: 1, contextLines: [ '{"name": "John", "age": 30}' ], characterPosition: 10 }
-     * ```
-     */
-    static extractLineInfoFromJsonError(errorMessage: string, jsonInput: string, contextLines?: number): JsonErrorLineInfo | null;
-    /**
-     * Helper method to create line info from a character position
-     * @param jsonInput - The original JSON input string
-     * @param position - The character position where the error occurred
-     * @param contextLines - Number of context lines to show before and after the error (default: 5)
-     * @returns Object containing line number, context lines, and character position
-     *
-     * @example
-     * ```ts
-     * const lineInfo = DyFM_JsonErrorHelper.createLineInfoFromPosition('{"name": "John", "age": 30}', 10, 5);
-     * console.log(lineInfo); // { lineNumber: 1, contextLines: [ '{"name": "John", "age": 30}' ], characterPosition: 10 }
-     * ```
-     */
-    private static createLineInfoFromPosition;
-    /**
-     * Formats JSON error information for logging
-     * Creates a formatted string showing the error location and context
-     *
-     * @param lineInfo - The line information extracted from the error
-     * @param errorMessage - The original error message
-     * @returns Formatted error string for logging
-     *
-     * @example
-     * ```ts
-     * const logLines = DyFM_JsonErrorHelper.formatJsonErrorForLogging({ lineNumber: 1, contextLines: [ '{"name": "John", "age": 30}' ], characterPosition: 10 }, 'Expected property name or "}" in JSON at position 10');
-     * console.log(logLines); // [ 'JSON parsing failed: Expected property name or "}" in JSON at position 10', 'Error at line 1, character 10:', 'Context (1 lines):', '    1: {"name": "John", "age": 30}' ]
-     * ```
-     */
-    static formatJsonErrorForLogging(lineInfo: JsonErrorLineInfo, errorMessage: string): string[];
-    /**
-     * Enhanced JSON.parse with detailed error reporting
-     * Wraps JSON.parse with enhanced error handling that shows line context
-     *
-     * @param jsonString - The JSON string to parse
-     * @param reviver - Optional reviver function for JSON.parse
-     * @param contextLines - Number of context lines to show in error (default: 5)
-     * @returns Parsed JSON object
-     * @throws Error with detailed line information if parsing fails
-     *
-     * @example
-     * ```ts
-     * const json = '{"name": "John", "age": 30}';
-     * const result = DyFM_JsonErrorHelper.parseJsonWithEnhancedError(json);
-     * console.log(result); // { name: 'John', age: 30 }
-     * ```
-     */
-    static parseJsonWithEnhancedError(jsonString: string, reviver?: (key: string, value: any) => any, contextLines?: number): any;
-    /**
-     * Formats single-line JSON with line breaks for better error reporting
-     * @param jsonString - The JSON string to format
-     * @returns The formatted JSON string
-     *
-     * @example
-     * ```ts
-     * const json = '{"name": "John", "age": 30, "city": "New York"}';
-     * const result = DyFM_JsonErrorHelper.formatJsonForBetterErrors(json);
-     * console.log(result); // '{\n  "name": "John",\n  "age": 30,\n  "city": "New York"\n}'
-     * ```
-     */
-    private static formatJsonForBetterErrors;
-}
+/**
+ * JSON Error Handling Helper Utilities
+ * Provides enhanced error handling for JSON parsing operations
+ *
+ * @author FutDevPro
+ * @version 1.0.0
+ */
+/**
+ * Interface for line information extracted from JSON parsing errors
+ */
+export interface JsonErrorLineInfo {
+    /** The line number where the error occurred */
+    lineNumber: number;
+    /** Array of context lines around the error (typically ±5 lines) */
+    contextLines: string[];
+    /** The character position within the line where the error occurred */
+    characterPosition: number;
+}
+/**
+ * Helper class for JSON error handling and enhanced parsing
+ */
+export declare class DyFM_JsonErrorHelper {
+    /**
+     * Extracts line information from JSON parsing error messages
+     * Parses error messages like "Expected property name or '}' in JSON at position 10"
+     * and returns the problematic line with surrounding context
+     *
+     * @param errorMessage - The JSON parsing error message
+     * @param jsonInput - The original JSON input string
+     * @param contextLines - Number of context lines to show before and after the error (default: 5)
+     * @returns Object containing line number, context lines, and character position, or null if parsing fails
+     *
+     * @example
+     * ```ts
+     * const lineInfo = DyFM_JsonErrorHelper.extractLineInfoFromJsonError('Expected property name or "}" in JSON at position 10', '{"name": "John", "age": 30}', 5);
+     * console.log(lineInfo); // { lineNumber: 1, contextLines: [ '{"name": "John", "age": 30}' ], characterPosition: 10 }
+     * ```
+     */
+    static extractLineInfoFromJsonError(errorMessage: string, jsonInput: string, contextLines?: number): JsonErrorLineInfo | null;
+    /**
+     * Helper method to create line info from a character position
+     * @param jsonInput - The original JSON input string
+     * @param position - The character position where the error occurred
+     * @param contextLines - Number of context lines to show before and after the error (default: 5)
+     * @returns Object containing line number, context lines, and character position
+     *
+     * @example
+     * ```ts
+     * const lineInfo = DyFM_JsonErrorHelper.createLineInfoFromPosition('{"name": "John", "age": 30}', 10, 5);
+     * console.log(lineInfo); // { lineNumber: 1, contextLines: [ '{"name": "John", "age": 30}' ], characterPosition: 10 }
+     * ```
+     */
+    private static createLineInfoFromPosition;
+    /**
+     * Formats JSON error information for logging
+     * Creates a formatted string showing the error location and context
+     *
+     * @param lineInfo - The line information extracted from the error
+     * @param errorMessage - The original error message
+     * @returns Formatted error string for logging
+     *
+     * @example
+     * ```ts
+     * const logLines = DyFM_JsonErrorHelper.formatJsonErrorForLogging({ lineNumber: 1, contextLines: [ '{"name": "John", "age": 30}' ], characterPosition: 10 }, 'Expected property name or "}" in JSON at position 10');
+     * console.log(logLines); // [ 'JSON parsing failed: Expected property name or "}" in JSON at position 10', 'Error at line 1, character 10:', 'Context (1 lines):', '    1: {"name": "John", "age": 30}' ]
+     * ```
+     */
+    static formatJsonErrorForLogging(lineInfo: JsonErrorLineInfo, errorMessage: string): string[];
+    /**
+     * Enhanced JSON.parse with detailed error reporting
+     * Wraps JSON.parse with enhanced error handling that shows line context
+     *
+     * @param jsonString - The JSON string to parse
+     * @param reviver - Optional reviver function for JSON.parse
+     * @param contextLines - Number of context lines to show in error (default: 5)
+     * @returns Parsed JSON object
+     * @throws Error with detailed line information if parsing fails
+     *
+     * @example
+     * ```ts
+     * const json = '{"name": "John", "age": 30}';
+     * const result = DyFM_JsonErrorHelper.parseJsonWithEnhancedError(json);
+     * console.log(result); // { name: 'John', age: 30 }
+     * ```
+     */
+    static parseJsonWithEnhancedError(jsonString: string, reviver?: (key: string, value: any) => any, contextLines?: number): any;
+    /**
+     * Formats single-line JSON with line breaks for better error reporting
+     * @param jsonString - The JSON string to format
+     * @returns The formatted JSON string
+     *
+     * @example
+     * ```ts
+     * const json = '{"name": "John", "age": 30, "city": "New York"}';
+     * const result = DyFM_JsonErrorHelper.formatJsonForBetterErrors(json);
+     * console.log(result); // '{\n  "name": "John",\n  "age": 30,\n  "city": "New York"\n}'
+     * ```
+     */
+    private static formatJsonForBetterErrors;
+}
 //# sourceMappingURL=json-error-helper.util.d.ts.map