Two Sum in TypeScript

 * Finds two numbers in an array that add up to a target and returns their indices.
 * Assumes exactly one solution exists, and each element can be used only once.
 * @param nums - An array of integers.
 * @param target - The target integer to find the sum for.
 * @returns Indices of the two numbers that add up to the target.
function twoSum(nums: number[], target: number): number[] {
    // Create a map to store the numbers and their indices.
    // The map will hold the value of the number as the key and its index as the value.
    const numMap: Map<number, number> = new Map();

    // Iterate through the array of numbers.
    for (let i = 0; i < nums.length; i++) {
        // Calculate the complement of the current number.
        // This is the number we need to find in the array to pair with the current number to reach the target.
        const complement: number = target - nums[i];

        // Check if the complement exists in the map.
        // If it does, it means we have found the two numbers which add up to the target.
        if (numMap.has(complement)) {
            // If complement is found, return the indices of the complement and the current number.
            return [numMap.get(complement)!, i];

        // If the complement is not found, add the current number and its index to the map.
        numMap.set(nums[i], i);

    // If no solution is found (which should not happen in this problem as per the constraints), return an empty array.
    // This line is more for TypeScript type safety, to ensure the function always returns a value.
    return [];