PLU-469: fix excel get table row implementation (#1006)

## Problem

Excel `getTopNTableRows` is buggy because `usedRange` includes all
non-empty cells (not limited to a table)
It can accidentally include:
- Stray formatting
- Other tables if you resize too far

There's no way to limit `usedRange` to a table specifically — it works
on worksheet or relative range context

## Solution
Considering using `range` which gives both the header row and data rows
as well as the `headerSheetRowIndex`, keeping the API call to still be
1: only select `values`, `rowCount` and `rowIndex` from the table to
speed up the query.

However, if the table is huge (>100k rows), it will take very long to
execute and timeout which is not ideal.

Settled for:
Using the `rows` API, and it involves pagination so the query takes
around 5s for a table of 50k rows
Also considered using the `columns` API, but it does not return the
`headerSheetRowIndex` address so another API query has to be made to
obtain it

Tried doing batching to save on 1 API call each but it takes around 2s
to perform the request even for small tables. Running a batch of 10
calls also take around 3s, making the tradeoff for running 1 batch of 2
calls not worth compared to 2 different API calls

Tested on staging that the query takes approximately the same time as
old method: 30 executions completed in 30s due to the excel queue rate
limit.

## Tests
`getTableRow` action:
- [x] Works for multiple found rows (the first row found is returned)
- [x] Values outside the table will not be retrieved

`updateTableRow` action:
- [x] Works for multiple found rows (the first row found is returned)
- [x] Values outside the table will not be retrieved

Author: m0nggh

packages/backend/src/apps/m365-excel/actions/get-table-row/implementation/get-top-n-table-rows.ts

@@ -2,6 +2,7 @@ import { type IGlobalVariable } from '@plumber/types'
 
 import z from 'zod'
 
+import HttpError from '@/errors/http'
 import StepError from '@/errors/step'
 
 import WorkbookSession from '../../../common/workbook-session'
@@ -16,13 +17,116 @@ const msGraphResponseSchema = z
     headerSheetRowIndex: response.rowIndex,
   }))
 
+// Can get more info e.g. formulas, numberFormat, text for possible date manipulation but too complex for now
+const msGraphRangeResponseSchema = z
+  .object({
+    rowCount: z.number(),
+    rowIndex: z.number(),
+    values: z.array(z.array(z.coerce.string())), // first row is the header
+  })
+  .transform((response) => {
+    if (response.values.length === 0) {
+      throw new Error('Excel table is missing the header row')
+    }
+    return {
+      rowCount: response.rowCount,
+      headerSheetRowIndex: response.rowIndex,
+      headerRowValues: response.values[0],
+      rowValues: response.values.slice(1),
+    }
+  })
+
 interface GetTopNTableRowsResult {
   columns: string[]
   rows: string[][]
   headerSheetRowIndex: number
 }
 
-export default async function getTopNTableRows(
+/**
+ * Using range endpoint to get both the header row and data rows
+ * instead of headerRowRange and rows to avoid extra API call
+ * Range endpoint API time taken (similar to the previous resized range method)
+ * - Around 0.5s for 50k rows with 5 columns of data
+ * - Around 0.25s for 25k rows with 3 columns of empty data
+ * - Around 0.15s for 10k rows with 3 columns of empty data
+ *
+ * Also, rows endpoint uses pagination so the query takes longer for large tables
+ * Rows endpoint API time taken:
+ * - Around 5s for 50k rows with 5 columns of data
+ * - Around 2s for 25k rows with 3 columns of empty data
+ * - Around 1s for 10k rows with 3 columns of empty data
+ *
+ * Considered using columns API but there is no headerSheetRowIndex returned so
+ * an extra API call has to be made to retrieve it
+ * Reference: https://learn.microsoft.com/en-us/graph/api/table-range?view=graph-rest-1.0&tabs=http
+ */
+export async function getTopNTableRows(
+  $: IGlobalVariable,
+  session: WorkbookSession,
+  tableId: string,
+  n: number,
+): Promise<GetTopNTableRowsResult> {
+  try {
+    const rangeParseResult = msGraphRangeResponseSchema.safeParse(
+      (
+        await session.request(
+          `/tables/${tableId}/range?$select=values,rowCount,rowIndex`,
+          'get',
+        )
+      ).data,
+    )
+
+    if (rangeParseResult.success === false) {
+      throw new StepError(
+        'Invalid table range',
+        'Check your Excel file and try again',
+        $.step.position,
+        $.app.name,
+      )
+    }
+
+    const { rowCount, headerSheetRowIndex, headerRowValues, rowValues } =
+      rangeParseResult.data
+
+    // rowCount includes the header row
+    if (rowCount > n + 1) {
+      throw new StepError(
+        `Your Excel table has more than ${n.toLocaleString()} rows.`,
+        `Reduce the number of rows and try again.`,
+        $.step.position,
+        $.app.name,
+      )
+    }
+
+    return {
+      columns: headerRowValues,
+      rows: rowValues,
+      headerSheetRowIndex,
+    }
+  } catch (error) {
+    if (error instanceof HttpError) {
+      if (
+        error.response.status === 400 &&
+        error.response.data.error.code === 'RangeExceedsLimit'
+      ) {
+        throw new StepError(
+          'Your Excel table is too large',
+          'Reduce the number of rows or columns and try again.',
+          $.step.position,
+          $.app.name,
+          error,
+        )
+      }
+    }
+    throw error
+  }
+}
+
+/**
+ * @deprecated Use getTopNTableRows instead
+ */
+// Old method in case we need to rollback fast
+export async function getTopNTableRowsOld(
   // Typically, we should avoid making $ viral though the codebase, but this is
   // an exception because getTopNTableRows is not a common helper function.
   $: IGlobalVariable,
@@ -86,3 +190,5 @@ export default async function getTopNTableRows(
     headerSheetRowIndex: tableRows.headerSheetRowIndex,
   }
 }
+
+export default getTopNTableRows