Deep Helper Function in TypeScript

This challenge asks you to create a versatile deep helper function in TypeScript. Deep helper functions are invaluable for traversing and manipulating nested data structures (objects and arrays) recursively, allowing you to perform operations like searching, updating, or filtering at any level of nesting. This is a common requirement in data processing, configuration management, and UI state handling.

Problem Description

You are tasked with implementing a generic deep helper function in TypeScript. This function should accept a target value, a callback function, and a data structure (which can be an object or an array). The callback function will be applied to each element within the data structure. If an element is an object or an array, the deep helper function should recursively call itself on that element. The callback function should receive the current value, the key (if the current value is a property of an object), and the path (an array of keys representing the path to the current value) as arguments.

Key Requirements:

• Generic Type: The function should be generic, allowing it to work with any data structure type.
• Recursive Traversal: The function must recursively traverse nested objects and arrays.
• Callback Execution: The callback function must be executed for each element.
• Path Tracking: The function must maintain and pass the path to each element in the data structure.
• Immutability (Important): The function should not modify the original data structure. It should return a new data structure with the modifications made by the callback.

Expected Behavior:

The function should return a new data structure with the same structure as the original, but with the values modified according to the callback function. If the callback returns undefined, the element should be removed from the new structure.

Edge Cases to Consider:

• Empty objects and arrays.
• Circular references (handle gracefully – avoid infinite loops).
• Primitive values (strings, numbers, booleans, null, undefined).
• Nested arrays within objects and vice versa.
• Callbacks that return null or undefined (should result in element removal).

Examples

Example 1:

Input:
data: { a: 1, b: { c: 2, d: 3 } },
target: 2,
callback: (value, key, path) => {
  if (value === target) {
    return value * 2;
  }
  return value;
}

Output:
{ a: 1, b: { c: 4, d: 3 } }

Explanation: The callback finds the value 2 (at path ['b', 'c']) and multiplies it by 2, returning 4.

Example 2:

Input:
data: [1, { a: 2, b: 3 }, 4],
target: 2,
callback: (value, key, path) => {
  if (value === target) {
    return undefined; // Remove the element
  }
  return value;
}

Output:
[1, { a: 2, b: 3 }, 4]  // Note: The callback returns undefined, but the original structure is not modified. The deep helper returns a new structure.

Explanation: The callback finds the value 2 (at path [1, 'a']) and returns `undefined`, indicating that the element should be removed from the *new* structure.

Example 3:

Input:
data: { a: { b: { c: 1 } }, d: [2, { e: 3 }] },
target: 1,
callback: (value, key, path) => {
  if (value === target) {
    return value + 1;
  }
  return value;
}

Output:
{ a: { b: { c: 2 } }, d: [2, { e: 3 }] }

Explanation: The callback finds the value 1 (at path ['a', 'b', 'c']) and increments it to 2.

Constraints

• The input data can be an object or an array.
• The callback function must accept three arguments: value, key, and path.
• The function must handle circular references gracefully (avoid infinite loops). A simple check for visited objects can be used.
• The function must not modify the original data structure.
• The path should be an array of strings or numbers representing the keys/indices.
• Performance: The function should be reasonably efficient for moderately sized data structures (up to a few levels of nesting and a few hundred elements).

Notes

• Consider using recursion to traverse the data structure.
• Use TypeScript generics to make the function type-safe.
• Pay close attention to the path tracking – it's crucial for providing context to the callback.
• Think about how to handle circular references to prevent infinite loops. A Set to track visited objects is a common approach.
• The immutability requirement is key. Create new objects and arrays instead of modifying the originals.
• The key argument in the callback will be undefined for elements that are not properties of an object (e.g., elements in an array).