@futdevpro/fsm-dynamo 1.16.4 → 1.16.7

package/src/_collections/utils/string.util.ts

@@ -1,450 +1,450 @@
-import { DyFM_StringCase } from './string-case.util';
-
-export interface DyFM_String_BracketSettings {
-  opening: string;
-  closing: string;
-}
-
-export interface DyFM_String_BracketDetailedResult {
-  content: string;
-  level: number;
-  brackets: DyFM_String_BracketSettings | null;
-}
-
-/**
- * String utility class
- */
-export class DyFM_String extends DyFM_StringCase {
-
-  /** 
-   * Removes \n, \r and spaces from the start and end of the string
-   * @param value - The string to trim
-   * @returns The trimmed string
-   */
-  static breakTrim(value: string): string {
-    return value.trim().replace(/(\r\n|\n|\r)/gm, '');
-  }
-
-  /**
-   * Splits strings into an array of strings, extracting contents between brackets with support for nesting.
-   * Returns an array where the first element is the input string with bracket contents replaced,
-   * followed by all extracted bracket contents at each depth level.
-   * 
-   * @param input - The input string to split
-   * @param openingBracket - The opening bracket to use
-   * @param closingBracket - The closing bracket to use
-   * @param maxDepth - The maximum depth to process nested brackets
-   * @param replaceContents - The string to replace bracket contents with in the main string
-   * @returns Array where first element is the modified string, followed by extracted contents
-   * 
-   * @example
-   * const input = 'asdasd (and other things) around (and layered things (and more layers) around) around';
-   * const result = DyFM_String.nestedBracketSplit(input, '(', ')', 2, '...');
-   * console.log(result);
-   * // Output: [
-   * //   'asdasd ... around ... around',
-   * //   'and other things',
-   * //   'and layered things ... around',
-   * //   'and more layers'
-   * // ]
-   */
-  static nestedBracketSplit(
-    input: string,
-    openingBracket: string,
-    closingBracket: string,
-    maxDepth: number = 10,
-    replaceContents?: string,
-  ): string[] {
-    const detailed = this.nestedBracketSplitDetailed(input, openingBracket, closingBracket, maxDepth, replaceContents);
-    return detailed.map(item => item.content);
-  }
-
-  /**
-   * Detailed version of nestedBracketSplit that returns comprehensive information about each extracted bracket content.
-   * Returns an array where the first element contains the modified string info,
-   * followed by detailed information about each extracted bracket content.
-   * 
-   * @param input - The input string to split
-   * @param openingBracket - The opening bracket to use
-   * @param closingBracket - The closing bracket to use
-   * @param maxDepth - The maximum depth to process nested brackets
-   * @param replaceContents - The string to replace bracket contents with in the main string
-   * @returns Array of objects with content, level, and bracket information
-   * 
-   * @example
-   * const input = 'asdasd (and other things) around (and layered things (and more layers) around) around';
-   * const result = DyFM_String.nestedBracketSplitDetailed(input, '(', ')', 2, '...');
-   * console.log(result);
-   * // Output: [
-   * //   { content: 'asdasd ... around ... around', level: 0, brackets: null },
-   * //   { content: 'and other things', level: 1, brackets: { opening: '(', closing: ')' } },
-   * //   { content: 'and layered things ... around', level: 1, brackets: { opening: '(', closing: ')' } },
-   * //   { content: 'and more layers', level: 2, brackets: { opening: '(', closing: ')' } }
-   * // ]
-   */
-  static nestedBracketSplitDetailed(
-    input: string,
-    openingBracket: string,
-    closingBracket: string,
-    maxDepth: number = 10,
-    replaceContents?: string,
-  ): DyFM_String_BracketDetailedResult[] {
-    const brackets = [{ opening: openingBracket, closing: closingBracket }];
-    return this.multiBracketSplitDetailed(input, brackets, maxDepth, replaceContents);
-  }
-
-  /**
-   * Splits strings into an array of strings, extracting contents between multiple types of brackets with support for nesting.
-   * Returns an array where the first element is the input string with bracket contents replaced,
-   * followed by all extracted bracket contents at each depth level.
-   * 
-   * @param input - The input string to split
-   * @param brackets - Array of bracket pairs with opening and closing strings
-   * @param maxDepth - The maximum depth to process nested brackets
-   * @param replaceContents - The string to replace bracket contents with in the main string
-   * @returns Array where first element is the modified string, followed by extracted contents
-   * 
-   * @example
-   * const input = 'text (round) and [square] with {curly (nested)} brackets';
-   * const brackets = [
-   *   { opening: '(', closing: ')' },
-   *   { opening: '[', closing: ']' },
-   *   { opening: '{', closing: '}' }
-   * ];
-   * const result = DyFM_String.multiBracketSplit(input, brackets, 2, '...');
-   * console.log(result);
-   * // Output: [
-   * //   'text ... and ... with ... brackets',
-   * //   'round',
-   * //   'square', 
-   * //   'curly ... ',
-   * //   'nested'
-   * // ]
-   */
-  static multiBracketSplit(
-    input: string,
-    brackets: DyFM_String_BracketSettings[],
-    maxDepth: number = 10,
-    replaceContents?: string,
-  ): string[] {
-    const detailed = this.multiBracketSplitDetailed(input, brackets, maxDepth, replaceContents);
-    return detailed.map(item => item.content);
-  }
-
-  /**
-   * Splits strings and returns detailed information about extracted bracket contents.
-   * Returns an array where the first element contains the modified string info,
-   * followed by detailed information about each extracted bracket content.
-   * 
-   * @param input - The input string to split
-   * @param brackets - Array of bracket pairs with opening and closing strings
-   * @param maxDepth - The maximum depth to process nested brackets
-   * @param replaceContents - The string to replace bracket contents with in the main string
-   * @returns Array of objects with content, level, and bracket information
-   * 
-   * @example
-   * const input = 'text (round) and [square] with {curly (nested)} brackets';
-   * const brackets = [
-   *   { opening: '(', closing: ')' },
-   *   { opening: '[', closing: ']' },
-   *   { opening: '{', closing: '}' }
-   * ];
-   * const result = DyFM_String.multiBracketSplitDetailed(input, brackets, 2, '...');
-   * console.log(result);
-   * // Output: [
-   * //   { content: 'text ... and ... with ... brackets', level: 0, brackets: null },
-   * //   { content: 'round', level: 1, brackets: { opening: '(', closing: ')' } },
-   * //   { content: 'square', level: 1, brackets: { opening: '[', closing: ']' } },
-   * //   { content: 'curly ...', level: 1, brackets: { opening: '{', closing: '}' } },
-   * //   { content: 'nested', level: 2, brackets: { opening: '(', closing: ')' } }
-   * // ]
-   */
-  static multiBracketSplitDetailed(
-    input: string,
-    brackets: DyFM_String_BracketSettings[],
-    maxDepth: number = 10,
-    replaceContents?: string,
-  ): DyFM_String_BracketDetailedResult[] {
-    if (brackets.length === 0) {
-      return [{ content: input, level: 0, brackets: null }];
-    }
-
-    const result: DyFM_String_BracketDetailedResult[] = [];
-    let workingPieces: DyFM_String_BracketDetailedResult[] = [
-      { content: input, level: 0, brackets: null }
-    ];
-    
-    for (let depth = 0; depth < maxDepth; depth++) {
-      const nextWorkingPieces: DyFM_String_BracketDetailedResult[] = [];
-      let foundAnyBrackets = false;
-
-      for (const piece of workingPieces) {
-        const extractedFromPiece = this.extractMultipleBracketsFromStringDetailed(
-          piece.content, 
-          brackets, 
-          replaceContents
-        );
-
-        if (extractedFromPiece.extracted.length > 0) {
-          foundAnyBrackets = true;
-          
-          // On first depth, store the modified string
-          if (depth === 0) {
-            result.push({ 
-              content: extractedFromPiece.modified, 
-              level: 0, 
-              brackets: null 
-            });
-          } else {
-            // On subsequent depths, update the piece in result
-            const pieceIndex = result.findIndex(r => r.content === piece.content && r.brackets === piece.brackets);
-            if (pieceIndex !== -1) {
-              result[pieceIndex].content = extractedFromPiece.modified;
-            }
-          }
-          
-          // Add extracted contents to result with their bracket information
-          for (const extracted of extractedFromPiece.extracted) {
-            result.push({
-              content: extracted.content,
-              level: depth + 1,
-              brackets: extracted.brackets
-            });
-          }
-          
-          // Add extracted contents for next iteration
-          for (const extracted of extractedFromPiece.extracted) {
-            nextWorkingPieces.push({
-              content: extracted.content,
-              level: depth + 1,
-              brackets: extracted.brackets ?? null
-            });
-          }
-        } else if (depth === 0) {
-          // No brackets found in input
-          result.push({ 
-            content: piece.content, 
-            level: 0, 
-            brackets: null 
-          });
-        }
-      }
-
-      if (!foundAnyBrackets) {
-        break;
-      }
-
-      workingPieces = nextWorkingPieces;
-    }
-
-    return result;
-  }
-
-  /**
-   * Helper method to extract multiple bracket types from a single string with detailed information
-   * @param input - The input string to extract the brackets from
-   * @param brackets - The brackets to extract
-   * @param replaceContents - The string to replace the brackets with
-   * @returns The modified string and the extracted brackets
-   * 
-   * @example
-   * ```ts
-   * const input = 'text (round) and [square] with {curly (nested)} brackets';
-   * const brackets = [
-   *   { opening: '(', closing: ')' },
-   *   { opening: '[', closing: ']' },
-   *   { opening: '{', closing: '}' }
-   * ];
-   * const result = DyFM_String.extractMultipleBracketsFromStringDetailed(input, brackets, '...');
-   * console.log(result);
-   * // Output: { modified: 'text ... and ... with ... brackets', extracted: [ { content: 'round', level: 1, brackets: { opening: '(', closing: ')' } }, { content: 'square', level: 1, brackets: { opening: '[', closing: ']' } }, { content: 'curly ...', level: 1, brackets: { opening: '{', closing: '}' } }, { content: 'nested', level: 2, brackets: { opening: '(', closing: ')' } } ] }
-   * ```
-   */
-  private static extractMultipleBracketsFromStringDetailed(
-    input: string,
-    brackets: DyFM_String_BracketSettings[],
-    replaceContents?: string
-  ): {
-    modified: string;
-    extracted: DyFM_String_BracketDetailedResult[]
-  } {
-    const extracted: DyFM_String_BracketDetailedResult[] = [];
-
-    // Unified scanning logic. If replaceContents is undefined, we preserve input in modified.
-    const preserveOriginal = replaceContents === undefined;
-    let modified = preserveOriginal ? input : '';
-
-    // We'll scan once with a combined stack to correctly respect top-level across all types.
-    type StackItem = {
-      id: number;
-      openingIndex: number;
-      // We store the originally assumed opening type index (may be reinterpreted on close if multiple closers share same opening)
-      type: number;
-      bracket: DyFM_String_BracketSettings;
-    };
-
-    let i = 0;
-    let idSeq = 1;
-    const stack: StackItem[] = [];
-
-    // Track current top-level segment start and the id of the bottom-of-stack item for the current top-level bracket
-    let topLevelStart = 0;
-    let activeTopId: number | null = null;
-
-    const appendTextUntil = (endIndex: number) => {
-      if (!preserveOriginal) {
-        modified += input.substring(topLevelStart, endIndex);
-      }
-    };
-
-    const closeTopLevel = (closeIndex: number, closedItem: StackItem, closingBracket: { opening: string; closing: string }, closeTokenLength: number) => {
-      // Extract content between the top-level opening and this close position
-      const content = input.substring(topLevelStart, closeIndex);
-      extracted.push({ content, level: 0, brackets: closingBracket });
-
-      if (!preserveOriginal) {
-        // Add replacement in place of the removed top-level content
-        modified += (replaceContents ?? '');
-      }
-
-      // Advance topLevelStart after the closing token
-      topLevelStart = closeIndex + closeTokenLength;
-
-      // Clear entire stack; any inner unclosed brackets are discarded as unmatched
-      stack.length = 0;
-      activeTopId = null;
-    };
-
-    while (i < input.length) {
-      let found = false;
-      let isOpening = false;
-      let matchLen = 0;
-      let matchType = -1;
-      // Track whether we've already selected an opening for a same-character bracket at this position
-      let selectedSameCharOpenType = -1;
-
-      // Determine the longest match among all brackets at this position for opening or closing.
-      for (let j = 0; j < brackets.length; j++) {
-        const b = brackets[j];
-
-        // Opening check
-        if (input.substring(i, i + b.opening.length) === b.opening) {
-          const len = b.opening.length;
-          // Decide opening vs closing when opening === closing (same character) using a heuristic
-          if (b.opening === b.closing) {
-            // Decide using immediate previous character: open at start/after whitespace or after an opening punctuation
-            const prevCharImmediate = i > 0 ? input[i - 1] : null;
-            const isOpenContext = (prevCharImmediate === null) || /[\s\(\[\{<]/.test(prevCharImmediate);
-            // If we can't possibly close (no such type open), we must open
-            const canCloseSameType = stack.some(s => s.bracket.opening === b.opening && s.bracket.closing === b.closing);
-
-            // Decide if we treat this token as opening
-            const treatAsOpening = isOpenContext || !canCloseSameType;
-            if (treatAsOpening && len > matchLen) {
-              found = true;
-              isOpening = true;
-              matchLen = len;
-              matchType = j;
-              selectedSameCharOpenType = j;
-            }
-          } else {
-            if (len > matchLen) {
-              found = true;
-              isOpening = true;
-              matchLen = len;
-              matchType = j;
-            }
-          }
-        }
-
-        // Closing check
-        if (input.substring(i, i + b.closing.length) === b.closing) {
-          const len = b.closing.length;
-          // For same-character brackets, prefer closing if there is an open of this type and we didn't already pick a longer opening
-          if (b.opening === b.closing) {
-            const canCloseSameType = stack.some(s => s.bracket.opening === b.opening && s.bracket.closing === b.closing);
-            // For same-character, allow closing to override only if it's strictly longer OR no same-char opening was chosen at this pos
-            if (canCloseSameType && (len > matchLen || (len === matchLen && selectedSameCharOpenType === -1))) {
-              found = true;
-              isOpening = false;
-              matchLen = len;
-              matchType = j;
-            }
-          } else {
-            // For normal brackets, only consider as closing if there's a matching opener in the stack (by type)
-            const hasExactType = stack.some(s => s.type === j);
-            const hasSameOpening = !hasExactType && stack.some(s => s.bracket.opening === b.opening);
-            if ((hasExactType || hasSameOpening) && len > matchLen) {
-              found = true;
-              isOpening = false;
-              matchLen = len;
-              matchType = j;
-            }
-          }
-        }
-      }
-
-      if (!found) {
-        i++;
-        continue;
-      }
-
-      const matchedBracket = brackets[matchType];
-
-      if (isOpening) {
-        // Start of a bracket segment
-        if (stack.length === 0) {
-          // Before the first top-level opening, append preceding text when replacing
-          appendTextUntil(i);
-          // Set the start of content (after opening token)
-          topLevelStart = i + matchLen;
-          activeTopId = idSeq;
-        }
-
-        stack.push({ id: idSeq++, openingIndex: i, type: matchType, bracket: matchedBracket });
-        i += matchLen;
-      } else {
-        // Determine which opener this closer should match.
-        // First, try to find an opener of the exact type (from the top of the stack downward)
-        let idx = -1;
-        for (let k = stack.length - 1; k >= 0; k--) {
-          if (stack[k].type === matchType) { idx = k; break; }
-        }
-        // If not found, allow matching by same opening string (handles cases like <...> and </>)
-        if (idx === -1) {
-          for (let k = stack.length - 1; k >= 0; k--) {
-            if (stack[k].bracket.opening === matchedBracket.opening) { idx = k; break; }
-          }
-        }
-
-        if (idx === -1) {
-          // No matching opener; treat as literal
-          i += matchLen;
-          continue;
-        }
-
-        const removed = stack.splice(idx, 1)[0];
-
-        // If we closed the bottom-most (top-level) opener, emit extraction and replacement
-        if (activeTopId !== null && removed.id === activeTopId) {
-          closeTopLevel(i, removed, matchedBracket, matchLen);
-        }
-
-        i += matchLen;
-      }
-    }
-
-    // Append any trailing text when replacing
-    if (!preserveOriginal && topLevelStart < input.length) {
-      modified += input.substring(topLevelStart);
-    }
-
-    // If preserving, modified must be original input
-    if (preserveOriginal) {
-      return { modified: input, extracted };
-    }
-
-    return { modified, extracted };
-  }
-
+import { DyFM_StringCase } from './string-case.util';
+
+export interface DyFM_String_BracketSettings {
+  opening: string;
+  closing: string;
+}
+
+export interface DyFM_String_BracketDetailedResult {
+  content: string;
+  level: number;
+  brackets: DyFM_String_BracketSettings | null;
+}
+
+/**
+ * String utility class
+ */
+export class DyFM_String extends DyFM_StringCase {
+
+  /** 
+   * Removes \n, \r and spaces from the start and end of the string
+   * @param value - The string to trim
+   * @returns The trimmed string
+   */
+  static breakTrim(value: string): string {
+    return value.trim().replace(/(\r\n|\n|\r)/gm, '');
+  }
+
+  /**
+   * Splits strings into an array of strings, extracting contents between brackets with support for nesting.
+   * Returns an array where the first element is the input string with bracket contents replaced,
+   * followed by all extracted bracket contents at each depth level.
+   * 
+   * @param input - The input string to split
+   * @param openingBracket - The opening bracket to use
+   * @param closingBracket - The closing bracket to use
+   * @param maxDepth - The maximum depth to process nested brackets
+   * @param replaceContents - The string to replace bracket contents with in the main string
+   * @returns Array where first element is the modified string, followed by extracted contents
+   * 
+   * @example
+   * const input = 'asdasd (and other things) around (and layered things (and more layers) around) around';
+   * const result = DyFM_String.nestedBracketSplit(input, '(', ')', 2, '...');
+   * console.log(result);
+   * // Output: [
+   * //   'asdasd ... around ... around',
+   * //   'and other things',
+   * //   'and layered things ... around',
+   * //   'and more layers'
+   * // ]
+   */
+  static nestedBracketSplit(
+    input: string,
+    openingBracket: string,
+    closingBracket: string,
+    maxDepth: number = 10,
+    replaceContents?: string,
+  ): string[] {
+    const detailed = this.nestedBracketSplitDetailed(input, openingBracket, closingBracket, maxDepth, replaceContents);
+    return detailed.map(item => item.content);
+  }
+
+  /**
+   * Detailed version of nestedBracketSplit that returns comprehensive information about each extracted bracket content.
+   * Returns an array where the first element contains the modified string info,
+   * followed by detailed information about each extracted bracket content.
+   * 
+   * @param input - The input string to split
+   * @param openingBracket - The opening bracket to use
+   * @param closingBracket - The closing bracket to use
+   * @param maxDepth - The maximum depth to process nested brackets
+   * @param replaceContents - The string to replace bracket contents with in the main string
+   * @returns Array of objects with content, level, and bracket information
+   * 
+   * @example
+   * const input = 'asdasd (and other things) around (and layered things (and more layers) around) around';
+   * const result = DyFM_String.nestedBracketSplitDetailed(input, '(', ')', 2, '...');
+   * console.log(result);
+   * // Output: [
+   * //   { content: 'asdasd ... around ... around', level: 0, brackets: null },
+   * //   { content: 'and other things', level: 1, brackets: { opening: '(', closing: ')' } },
+   * //   { content: 'and layered things ... around', level: 1, brackets: { opening: '(', closing: ')' } },
+   * //   { content: 'and more layers', level: 2, brackets: { opening: '(', closing: ')' } }
+   * // ]
+   */
+  static nestedBracketSplitDetailed(
+    input: string,
+    openingBracket: string,
+    closingBracket: string,
+    maxDepth: number = 10,
+    replaceContents?: string,
+  ): DyFM_String_BracketDetailedResult[] {
+    const brackets = [{ opening: openingBracket, closing: closingBracket }];
+    return this.multiBracketSplitDetailed(input, brackets, maxDepth, replaceContents);
+  }
+
+  /**
+   * Splits strings into an array of strings, extracting contents between multiple types of brackets with support for nesting.
+   * Returns an array where the first element is the input string with bracket contents replaced,
+   * followed by all extracted bracket contents at each depth level.
+   * 
+   * @param input - The input string to split
+   * @param brackets - Array of bracket pairs with opening and closing strings
+   * @param maxDepth - The maximum depth to process nested brackets
+   * @param replaceContents - The string to replace bracket contents with in the main string
+   * @returns Array where first element is the modified string, followed by extracted contents
+   * 
+   * @example
+   * const input = 'text (round) and [square] with {curly (nested)} brackets';
+   * const brackets = [
+   *   { opening: '(', closing: ')' },
+   *   { opening: '[', closing: ']' },
+   *   { opening: '{', closing: '}' }
+   * ];
+   * const result = DyFM_String.multiBracketSplit(input, brackets, 2, '...');
+   * console.log(result);
+   * // Output: [
+   * //   'text ... and ... with ... brackets',
+   * //   'round',
+   * //   'square', 
+   * //   'curly ... ',
+   * //   'nested'
+   * // ]
+   */
+  static multiBracketSplit(
+    input: string,
+    brackets: DyFM_String_BracketSettings[],
+    maxDepth: number = 10,
+    replaceContents?: string,
+  ): string[] {
+    const detailed = this.multiBracketSplitDetailed(input, brackets, maxDepth, replaceContents);
+    return detailed.map(item => item.content);
+  }
+
+  /**
+   * Splits strings and returns detailed information about extracted bracket contents.
+   * Returns an array where the first element contains the modified string info,
+   * followed by detailed information about each extracted bracket content.
+   * 
+   * @param input - The input string to split
+   * @param brackets - Array of bracket pairs with opening and closing strings
+   * @param maxDepth - The maximum depth to process nested brackets
+   * @param replaceContents - The string to replace bracket contents with in the main string
+   * @returns Array of objects with content, level, and bracket information
+   * 
+   * @example
+   * const input = 'text (round) and [square] with {curly (nested)} brackets';
+   * const brackets = [
+   *   { opening: '(', closing: ')' },
+   *   { opening: '[', closing: ']' },
+   *   { opening: '{', closing: '}' }
+   * ];
+   * const result = DyFM_String.multiBracketSplitDetailed(input, brackets, 2, '...');
+   * console.log(result);
+   * // Output: [
+   * //   { content: 'text ... and ... with ... brackets', level: 0, brackets: null },
+   * //   { content: 'round', level: 1, brackets: { opening: '(', closing: ')' } },
+   * //   { content: 'square', level: 1, brackets: { opening: '[', closing: ']' } },
+   * //   { content: 'curly ...', level: 1, brackets: { opening: '{', closing: '}' } },
+   * //   { content: 'nested', level: 2, brackets: { opening: '(', closing: ')' } }
+   * // ]
+   */
+  static multiBracketSplitDetailed(
+    input: string,
+    brackets: DyFM_String_BracketSettings[],
+    maxDepth: number = 10,
+    replaceContents?: string,
+  ): DyFM_String_BracketDetailedResult[] {
+    if (brackets.length === 0) {
+      return [{ content: input, level: 0, brackets: null }];
+    }
+
+    const result: DyFM_String_BracketDetailedResult[] = [];
+    let workingPieces: DyFM_String_BracketDetailedResult[] = [
+      { content: input, level: 0, brackets: null }
+    ];
+    
+    for (let depth = 0; depth < maxDepth; depth++) {
+      const nextWorkingPieces: DyFM_String_BracketDetailedResult[] = [];
+      let foundAnyBrackets = false;
+
+      for (const piece of workingPieces) {
+        const extractedFromPiece = this.extractMultipleBracketsFromStringDetailed(
+          piece.content, 
+          brackets, 
+          replaceContents
+        );
+
+        if (extractedFromPiece.extracted.length > 0) {
+          foundAnyBrackets = true;
+          
+          // On first depth, store the modified string
+          if (depth === 0) {
+            result.push({ 
+              content: extractedFromPiece.modified, 
+              level: 0, 
+              brackets: null 
+            });
+          } else {
+            // On subsequent depths, update the piece in result
+            const pieceIndex = result.findIndex(r => r.content === piece.content && r.brackets === piece.brackets);
+            if (pieceIndex !== -1) {
+              result[pieceIndex].content = extractedFromPiece.modified;
+            }
+          }
+          
+          // Add extracted contents to result with their bracket information
+          for (const extracted of extractedFromPiece.extracted) {
+            result.push({
+              content: extracted.content,
+              level: depth + 1,
+              brackets: extracted.brackets
+            });
+          }
+          
+          // Add extracted contents for next iteration
+          for (const extracted of extractedFromPiece.extracted) {
+            nextWorkingPieces.push({
+              content: extracted.content,
+              level: depth + 1,
+              brackets: extracted.brackets ?? null
+            });
+          }
+        } else if (depth === 0) {
+          // No brackets found in input
+          result.push({ 
+            content: piece.content, 
+            level: 0, 
+            brackets: null 
+          });
+        }
+      }
+
+      if (!foundAnyBrackets) {
+        break;
+      }
+
+      workingPieces = nextWorkingPieces;
+    }
+
+    return result;
+  }
+
+  /**
+   * Helper method to extract multiple bracket types from a single string with detailed information
+   * @param input - The input string to extract the brackets from
+   * @param brackets - The brackets to extract
+   * @param replaceContents - The string to replace the brackets with
+   * @returns The modified string and the extracted brackets
+   * 
+   * @example
+   * ```ts
+   * const input = 'text (round) and [square] with {curly (nested)} brackets';
+   * const brackets = [
+   *   { opening: '(', closing: ')' },
+   *   { opening: '[', closing: ']' },
+   *   { opening: '{', closing: '}' }
+   * ];
+   * const result = DyFM_String.extractMultipleBracketsFromStringDetailed(input, brackets, '...');
+   * console.log(result);
+   * // Output: { modified: 'text ... and ... with ... brackets', extracted: [ { content: 'round', level: 1, brackets: { opening: '(', closing: ')' } }, { content: 'square', level: 1, brackets: { opening: '[', closing: ']' } }, { content: 'curly ...', level: 1, brackets: { opening: '{', closing: '}' } }, { content: 'nested', level: 2, brackets: { opening: '(', closing: ')' } } ] }
+   * ```
+   */
+  private static extractMultipleBracketsFromStringDetailed(
+    input: string,
+    brackets: DyFM_String_BracketSettings[],
+    replaceContents?: string
+  ): {
+    modified: string;
+    extracted: DyFM_String_BracketDetailedResult[]
+  } {
+    const extracted: DyFM_String_BracketDetailedResult[] = [];
+
+    // Unified scanning logic. If replaceContents is undefined, we preserve input in modified.
+    const preserveOriginal = replaceContents === undefined;
+    let modified = preserveOriginal ? input : '';
+
+    // We'll scan once with a combined stack to correctly respect top-level across all types.
+    type StackItem = {
+      id: number;
+      openingIndex: number;
+      // We store the originally assumed opening type index (may be reinterpreted on close if multiple closers share same opening)
+      type: number;
+      bracket: DyFM_String_BracketSettings;
+    };
+
+    let i = 0;
+    let idSeq = 1;
+    const stack: StackItem[] = [];
+
+    // Track current top-level segment start and the id of the bottom-of-stack item for the current top-level bracket
+    let topLevelStart = 0;
+    let activeTopId: number | null = null;
+
+    const appendTextUntil = (endIndex: number) => {
+      if (!preserveOriginal) {
+        modified += input.substring(topLevelStart, endIndex);
+      }
+    };
+
+    const closeTopLevel = (closeIndex: number, closedItem: StackItem, closingBracket: { opening: string; closing: string }, closeTokenLength: number) => {
+      // Extract content between the top-level opening and this close position
+      const content = input.substring(topLevelStart, closeIndex);
+      extracted.push({ content, level: 0, brackets: closingBracket });
+
+      if (!preserveOriginal) {
+        // Add replacement in place of the removed top-level content
+        modified += (replaceContents ?? '');
+      }
+
+      // Advance topLevelStart after the closing token
+      topLevelStart = closeIndex + closeTokenLength;
+
+      // Clear entire stack; any inner unclosed brackets are discarded as unmatched
+      stack.length = 0;
+      activeTopId = null;
+    };
+
+    while (i < input.length) {
+      let found = false;
+      let isOpening = false;
+      let matchLen = 0;
+      let matchType = -1;
+      // Track whether we've already selected an opening for a same-character bracket at this position
+      let selectedSameCharOpenType = -1;
+
+      // Determine the longest match among all brackets at this position for opening or closing.
+      for (let j = 0; j < brackets.length; j++) {
+        const b = brackets[j];
+
+        // Opening check
+        if (input.substring(i, i + b.opening.length) === b.opening) {
+          const len = b.opening.length;
+          // Decide opening vs closing when opening === closing (same character) using a heuristic
+          if (b.opening === b.closing) {
+            // Decide using immediate previous character: open at start/after whitespace or after an opening punctuation
+            const prevCharImmediate = i > 0 ? input[i - 1] : null;
+            const isOpenContext = (prevCharImmediate === null) || /[\s\(\[\{<]/.test(prevCharImmediate);
+            // If we can't possibly close (no such type open), we must open
+            const canCloseSameType = stack.some(s => s.bracket.opening === b.opening && s.bracket.closing === b.closing);
+
+            // Decide if we treat this token as opening
+            const treatAsOpening = isOpenContext || !canCloseSameType;
+            if (treatAsOpening && len > matchLen) {
+              found = true;
+              isOpening = true;
+              matchLen = len;
+              matchType = j;
+              selectedSameCharOpenType = j;
+            }
+          } else {
+            if (len > matchLen) {
+              found = true;
+              isOpening = true;
+              matchLen = len;
+              matchType = j;
+            }
+          }
+        }
+
+        // Closing check
+        if (input.substring(i, i + b.closing.length) === b.closing) {
+          const len = b.closing.length;
+          // For same-character brackets, prefer closing if there is an open of this type and we didn't already pick a longer opening
+          if (b.opening === b.closing) {
+            const canCloseSameType = stack.some(s => s.bracket.opening === b.opening && s.bracket.closing === b.closing);
+            // For same-character, allow closing to override only if it's strictly longer OR no same-char opening was chosen at this pos
+            if (canCloseSameType && (len > matchLen || (len === matchLen && selectedSameCharOpenType === -1))) {
+              found = true;
+              isOpening = false;
+              matchLen = len;
+              matchType = j;
+            }
+          } else {
+            // For normal brackets, only consider as closing if there's a matching opener in the stack (by type)
+            const hasExactType = stack.some(s => s.type === j);
+            const hasSameOpening = !hasExactType && stack.some(s => s.bracket.opening === b.opening);
+            if ((hasExactType || hasSameOpening) && len > matchLen) {
+              found = true;
+              isOpening = false;
+              matchLen = len;
+              matchType = j;
+            }
+          }
+        }
+      }
+
+      if (!found) {
+        i++;
+        continue;
+      }
+
+      const matchedBracket = brackets[matchType];
+
+      if (isOpening) {
+        // Start of a bracket segment
+        if (stack.length === 0) {
+          // Before the first top-level opening, append preceding text when replacing
+          appendTextUntil(i);
+          // Set the start of content (after opening token)
+          topLevelStart = i + matchLen;
+          activeTopId = idSeq;
+        }
+
+        stack.push({ id: idSeq++, openingIndex: i, type: matchType, bracket: matchedBracket });
+        i += matchLen;
+      } else {
+        // Determine which opener this closer should match.
+        // First, try to find an opener of the exact type (from the top of the stack downward)
+        let idx = -1;
+        for (let k = stack.length - 1; k >= 0; k--) {
+          if (stack[k].type === matchType) { idx = k; break; }
+        }
+        // If not found, allow matching by same opening string (handles cases like <...> and </>)
+        if (idx === -1) {
+          for (let k = stack.length - 1; k >= 0; k--) {
+            if (stack[k].bracket.opening === matchedBracket.opening) { idx = k; break; }
+          }
+        }
+
+        if (idx === -1) {
+          // No matching opener; treat as literal
+          i += matchLen;
+          continue;
+        }
+
+        const removed = stack.splice(idx, 1)[0];
+
+        // If we closed the bottom-most (top-level) opener, emit extraction and replacement
+        if (activeTopId !== null && removed.id === activeTopId) {
+          closeTopLevel(i, removed, matchedBracket, matchLen);
+        }
+
+        i += matchLen;
+      }
+    }
+
+    // Append any trailing text when replacing
+    if (!preserveOriginal && topLevelStart < input.length) {
+      modified += input.substring(topLevelStart);
+    }
+
+    // If preserving, modified must be original input
+    if (preserveOriginal) {
+      return { modified: input, extracted };
+    }
+
+    return { modified, extracted };
+  }
+
 }