@futdevpro/fsm-dynamo 1.20.88 → 1.20.93

package/build-esm/_collections/utils/json-error-helper.util.js

@@ -0,0 +1,251 @@
+/**
+ * JSON Error Handling Helper Utilities
+ * Provides enhanced error handling for JSON parsing operations
+ *
+ * @author FutDevPro
+ * @version 1.0.0
+ */
+/**
+ * Helper class for JSON error handling and enhanced parsing
+ */
+export 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, jsonInput, contextLines = 5) {
+        try {
+            // Extract position from various error message formats
+            let positionMatch = errorMessage.match(/at position (\d+)/);
+            if (!positionMatch) {
+                // Handle "Unexpected end of JSON input at position 17" format
+                positionMatch = errorMessage.match(/Unexpected end of JSON input at position (\d+)/);
+            }
+            if (!positionMatch) {
+                // Handle "Unexpected token" format which might include position
+                positionMatch = errorMessage.match(/position (\d+)/);
+            }
+            if (!positionMatch) {
+                // For "Unexpected token" errors without explicit position, try to find it from the token
+                const tokenMatch = errorMessage.match(/Unexpected token '(.)'|Unexpected token (.)/);
+                if (tokenMatch && jsonInput.includes('\n')) {
+                    const token = tokenMatch[1] || tokenMatch[2];
+                    if (token) {
+                        // Find the first occurrence of this token (this is a simple heuristic)
+                        const tokenPosition = jsonInput.indexOf(token);
+                        if (tokenPosition !== -1) {
+                            return this.createLineInfoFromPosition(jsonInput, tokenPosition, contextLines);
+                        }
+                    }
+                }
+                return null;
+            }
+            const position = parseInt(positionMatch[1], 10);
+            if (isNaN(position) || position < 0) {
+                return null;
+            }
+            // For end-of-input errors, position might be at or beyond the string length
+            // Allow position to be equal to jsonInput.length for end-of-input cases
+            if (position > jsonInput.length) {
+                return null;
+            }
+            return this.createLineInfoFromPosition(jsonInput, position, contextLines);
+        }
+        catch (error) {
+            // If we can't parse the error, return null to fall back to simple preview
+            return 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 }
+     * ```
+     */
+    static createLineInfoFromPosition(jsonInput, position, contextLines) {
+        // Handle undefined or invalid input
+        if (!jsonInput || typeof jsonInput !== 'string') {
+            return {
+                lineNumber: 1,
+                contextLines: ['(invalid or empty input)'],
+                characterPosition: 0
+            };
+        }
+        // Split input into lines to find the line number
+        const lines = jsonInput.split('\n');
+        let currentPosition = 0;
+        let lineNumber = 1;
+        let characterPosition = 0;
+        for (let i = 0; i < lines.length; i++) {
+            const lineLength = lines[i].length;
+            if (currentPosition + lineLength >= position) {
+                lineNumber = i + 1;
+                characterPosition = position - currentPosition;
+                break;
+            }
+            currentPosition += lineLength + 1; // +1 for newline character
+        }
+        // If we didn't find the line in the loop, it's at the end
+        if (characterPosition === 0 && lineNumber === 1) {
+            lineNumber = lines.length;
+            characterPosition = position - currentPosition;
+        }
+        // Ensure character position is not negative
+        if (characterPosition < 0) {
+            characterPosition = 0;
+        }
+        // Ensure line number is within bounds
+        if (lineNumber > lines.length) {
+            lineNumber = lines.length;
+        }
+        // Get surrounding context (±contextLines)
+        const contextStart = Math.max(0, lineNumber - contextLines - 1);
+        const contextEnd = Math.min(lines.length, lineNumber + contextLines);
+        const contextLinesArray = lines.slice(contextStart, contextEnd);
+        return {
+            lineNumber,
+            contextLines: contextLinesArray,
+            characterPosition
+        };
+    }
+    /**
+     * 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, errorMessage) {
+        const logLines = [];
+        logLines.push(`JSON parsing failed: ${errorMessage}`);
+        logLines.push(`Error at line ${lineInfo.lineNumber}, character ${lineInfo.characterPosition}:`);
+        logLines.push(`Context (${lineInfo.contextLines.length} lines):`);
+        // Calculate the starting line number for context
+        const contextStartLine = Math.max(1, lineInfo.lineNumber - Math.floor(lineInfo.contextLines.length / 2));
+        lineInfo.contextLines.forEach((line, index) => {
+            const lineNum = contextStartLine + index;
+            const marker = lineNum === lineInfo.lineNumber ? '>>> ' : '    ';
+            const lineContent = line || '(empty line)';
+            logLines.push(`${marker}${lineNum.toString().padStart(3)}: ${lineContent}`);
+        });
+        return logLines;
+    }
+    /**
+     * 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, reviver, contextLines = 2) {
+        // Prevent infinite recursion and handle invalid input
+        if (!jsonString || typeof jsonString !== 'string') {
+            throw new Error(`Invalid JSON input: expected string, got ${typeof jsonString}`);
+        }
+        try {
+            return JSON.parse(jsonString, reviver);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            const originalJsonString = jsonString;
+            // First try to extract line info from the original JSON
+            let lineInfo = this.extractLineInfoFromJsonError(errorMessage, originalJsonString, contextLines);
+            // If no line info was found and the JSON is on a single line, try formatting it
+            if (!lineInfo && !originalJsonString.includes('\n')) {
+                try {
+                    const formattedJson = this.formatJsonForBetterErrors(originalJsonString);
+                    // Try parsing the formatted JSON to get a new error with position info
+                    try {
+                        JSON.parse(formattedJson, reviver);
+                    }
+                    catch (formattedError) {
+                        const formattedErrorMessage = formattedError instanceof Error ? formattedError.message : String(formattedError);
+                        lineInfo = this.extractLineInfoFromJsonError(formattedErrorMessage, formattedJson, contextLines);
+                    }
+                }
+                catch (formatError) {
+                    // If formatting fails, skip enhanced error reporting
+                    lineInfo = null;
+                }
+            }
+            if (lineInfo) {
+                const formattedError = this.formatJsonErrorForLogging(lineInfo, errorMessage);
+                throw new Error(`JSON parsing failed:\n${formattedError.join('\n')}`);
+            }
+            else {
+                // Fallback to simple error if we can't extract line info
+                throw new Error(`JSON parsing failed: ${errorMessage}`);
+            }
+        }
+    }
+    /**
+     * 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}'
+     * ```
+     */
+    static formatJsonForBetterErrors(jsonString) {
+        if (!jsonString || typeof jsonString !== 'string') {
+            return jsonString || '';
+        }
+        return jsonString
+            .replace(/,/g, ',\n  ')
+            .replace(/{/g, '{\n  ')
+            .replace(/}/g, '\n}')
+            .replace(/\[/g, '[\n  ')
+            .replace(/\]/g, '\n]')
+            .replace(/\n\s*\n/g, '\n') // Remove double newlines
+            .replace(/^\s+|\s+$/gm, function (match, offset, string) {
+            // Trim but preserve indentation structure
+            if (!string || typeof string !== 'string') {
+                return match;
+            }
+            const lines = string.slice(0, offset).split('\n');
+            const depth = (string.slice(0, offset).match(/{|\[/g) || []).length -
+                (string.slice(0, offset).match(/}|\]/g) || []).length;
+            return '  '.repeat(Math.max(0, depth));
+        });
+    }
+}