require2DArray

function require2DArray<T>(
  value: unknown,
  message: string = "Expected a non-empty two-dimensional array."
): T[][];

The check to put in front of Range#setValues, which rejects a flat array with a message that names neither the argument nor the reason. require2DArray throws first, with a message you control, and returns the value so the call composes into an expression.

It accepts exactly what is2DArray accepts: a non-empty array whose every element is an array. Rows of differing length pass — use requireConsistent2DArray when they must match.

Parameters

Parameter	Type	Description
`value`	`unknown`	The value to validate.
`message` (optional) `= "Expected a non-empty two-dimensional array."`	`string`	The exception message. Defaults to `"Expected a non-empty two-dimensional array."`

Returns

T[][] — the same value, typed as a two-dimensional array.

Throws

Exception	Condition
`IllegalArgumentException`	The value is not a non-empty array of arrays.

Examples

Validating and using in one expression

/**
 * Validates the argument at the boundary of the function, with a message that
 * names the argument, and uses the validated value in the same expression.
 */
export function writeRows(sheet: GoogleAppsScript.Spreadsheet.Sheet, values: unknown): void {
  const rows = require2DArray<string>(values, "values must be a matrix of rows");

  sheet.getRange(1, 1, rows.length, rows[0].length).setValues(rows);
}

function writeRows(sheet, values) {
  const rows = require2DArray(values, "values must be a matrix of rows");
  sheet.getRange(1, 1, rows.length, rows[0].length).setValues(rows);
}

What passes and what throws

require2DArray([
  [1, 2],
  [3, 4]
]); // => [[1, 2], [3, 4]]
require2DArray([1, 2]); // throws IllegalArgumentException
require2DArray([]); // throws IllegalArgumentException — no rows

Source

src/lang/array/require2DArray.ts

23 September 2026

This documentation was generated with AI (Claude) from the library's source code.

apps-script-utils 2.1.1 Help