Stochastic (STOCH)

/**
 * Calculates the Stochastic Oscillator for a given dataset and period.
 *
 * @param {array} data An array of historical stock data. Expected to have at least 5 columns (Date, Open, High, Low, Close).
 * @param {number} period - The number of periods for calculating the Stochastic Oscillator.
 * @returns {array} - A 2D array with headers: Date, %K, %D.
 * @customfunction
 */
function STOCH(data, period) {
  // Argument validation
  if (arguments.length !== 2) {
    throw new Error(`Wrong number of arguments. Expected 2, but got ${arguments.length}.`);
  }
  if (typeof period !== 'number' || period <= 0 || !Number.isInteger(period)) {
    throw new Error(`Invalid period. The period must be a positive integer. Got: ${period}`);
  }

  const processedData = getData(data);

  // --- NEW: Function-level validation ---
  const columnCount = processedData[0].length;
  if (columnCount < 5) {
    throw new Error(`Invalid data structure for Stochastic Oscillator. Expected at least 5 columns (Date, Open, High, Low, Close), but got ${columnCount}.`);
  }
  // --- END of validation ---

  const dates = processedData.slice(1).map(row => row[0]);
  const highs = processedData.slice(1).map(row => row[2]);
  const lows = processedData.slice(1).map(row => row[3]);
  const closes = processedData.slice(1).map(row => row[4]);

  if (period > closes.length) {
    throw new Error(`Invalid period. The period (${period}) cannot be greater than the number of data points (${closes.length}).`);
  }

  const kValues = [];
  for (let i = period - 1; i < closes.length; i++) {
    const periodHigh = Math.max(...highs.slice(i - period + 1, i + 1));
    const periodLow = Math.min(...lows.slice(i - period + 1, i + 1));
    const currentClose = closes[i];

    // Avoid division by zero if periodHigh === periodLow
    let kValue;
    if (periodHigh === periodLow) {
        kValue = 0; // Or handle as an error/NaN depending on desired behavior
    } else {
        kValue = ((currentClose - periodLow) / (periodHigh - periodLow)) * 100;
    }
    kValues.push([dates[i], kValue]);
  }

  // Calculate %D (3-period SMA of %K)
  // SMA expects data in [date, value] format, which kValues already is.
  const dValues = SMA(kValues, 3).slice(1); // Remove headers

  // Align %K and %D lengths
  const [alignedK, alignedD] = alignLENGTHS(kValues, dValues);

  // Combine %K and %D values into final output
  const stochValues = alignedK.map((k, i) => {
    return [k[0], k[1], alignedD[i] ? alignedD[i][1] : null];
  });

  return [["Date", "%K", "%D"], ...stochValues];
}