@futdevpro/fsm-dynamo 1.16.27 → 1.16.29

package/src/_collections/utils/json-error-helper.util.ts

@@ -1,302 +1,302 @@
-/**
- * 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 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 = 5
-  ): JsonErrorLineInfo | null {
-    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 }
-   * ```
-   */
-  private static createLineInfoFromPosition(
-    jsonInput: string, 
-    position: number, 
-    contextLines: number
-  ): JsonErrorLineInfo {
-    // 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: JsonErrorLineInfo, 
-    errorMessage: string
-  ): string[] {
-    const logLines: string[] = [];
-    
-    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: string, 
-    reviver?: (key: string, value: any) => any,
-    contextLines: number = 2
-  ): any {
-    // 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}'
-   * ```
-   */
-  private static formatJsonForBetterErrors(jsonString: string): string {
-    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: string, offset: number, string: string): string {
-        // Trim but preserve indentation structure
-        if (!string || typeof string !== 'string') {
-          return match;
-        }
-        const lines: string[] = string.slice(0, offset).split('\n');
-        const depth: number = (string.slice(0, offset).match(/{|\[/g) || []).length - 
-                     (string.slice(0, offset).match(/}|\]/g) || []).length;
-
-        return '  '.repeat(Math.max(0, depth));
-      });
-  }
+/**
+ * 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 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 = 5
+  ): JsonErrorLineInfo | null {
+    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 }
+   * ```
+   */
+  private static createLineInfoFromPosition(
+    jsonInput: string, 
+    position: number, 
+    contextLines: number
+  ): JsonErrorLineInfo {
+    // 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: JsonErrorLineInfo, 
+    errorMessage: string
+  ): string[] {
+    const logLines: string[] = [];
+    
+    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: string, 
+    reviver?: (key: string, value: any) => any,
+    contextLines: number = 2
+  ): any {
+    // 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}'
+   * ```
+   */
+  private static formatJsonForBetterErrors(jsonString: string): string {
+    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: string, offset: number, string: string): string {
+        // Trim but preserve indentation structure
+        if (!string || typeof string !== 'string') {
+          return match;
+        }
+        const lines: string[] = string.slice(0, offset).split('\n');
+        const depth: number = (string.slice(0, offset).match(/{|\[/g) || []).length - 
+                     (string.slice(0, offset).match(/}|\]/g) || []).length;
+
+        return '  '.repeat(Math.max(0, depth));
+      });
+  }
 }