requireConsistent2DArray

function requireConsistent2DArray<T>(value: unknown, message?: string): T[][];

The strict counterpart of require2DArray: the value must be a non-empty array of arrays and every row must be as wide as the first.

When the rows differ, the default message reports the offending row and both widths — the information needed to fix the call, and precisely what Range#setValues withholds when it rejects a ragged matrix. A custom message replaces the default in both failure cases.

Parameters

Parameter	Type	Description
`value`	`unknown`	The value to validate.
`message` (optional)	`string`	The exception message. A default describing the mismatch is used when omitted.

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.
`IllegalArgumentException`	The rows do not all have the same length.

Examples

A matrix that is safe to write

/**
 * Accepts only a matrix whose rows are all the same width. The default message
 * names the offending row and both widths.
 */
export function writeMatrix(sheet: GoogleAppsScript.Spreadsheet.Sheet, values: unknown): void {
  const rows = requireConsistent2DArray<string>(values);

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

function writeMatrix(sheet, values) {
  const rows = requireConsistent2DArray(values);
  sheet.getRange(1, 1, rows.length, rows[0].length).setValues(rows);
}

The message names the offending row

requireConsistent2DArray([
  [1, 2],
  [3, 4]
]); // => [[1, 2], [3, 4]]

requireConsistent2DArray([[1, 2], [3]]);
// throws IllegalArgumentException:
// Expected every row to have 2 columns, but row 1 has 1.

requireConsistent2DArray([1, 2], "rows must be a matrix");
// throws IllegalArgumentException: rows must be a matrix

Source

src/lang/array/requireConsistent2DArray.ts

23 September 2026

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

apps-script-utils 2.1.1 Help