is2DArray

function is2DArray(arr: unknown): arr is Array<Array<unknown>>;

This is the shape Range#getValues returns and Range#setValues expects: rows holding cells. is2DArray answers only the shape question — whether the rows all have the same length is isConsistent2DArray.

An empty array is not two-dimensional here: there are no rows to examine, and treating [] as a matrix is what lets an empty result slip through into a setValues call that then fails. Nothing else about the elements is inspected, so a matrix of mixed types passes.

As a TypeScript type predicate it narrows the value to Array<Array<unknown>> inside the branch.

Parameters

Parameter	Type	Description
`arr`	`unknown`	The value to check.

Returns

boolean — true if the value is a non-empty array and every element of it is an array; otherwise false.

In TypeScript the guard narrows arr to Array<Array<unknown>> inside the branch.

Examples

What counts as two-dimensional

is2DArray([[1, 2], [3]]); // => true — ragged, but still 2D
is2DArray([[1], 2]); // => false — one element is not an array
is2DArray([]); // => false — no rows
is2DArray("abc"); // => false

Guarding a value that may be a matrix

/**
 * Counts the cells of a value that may or may not be a matrix. Inside the
 * guard the value is narrowed to `Array<Array<unknown>>`.
 */
export function countCells(value: unknown): number {
  if (!is2DArray(value)) {
    return 0;
  }

  return value.reduce((total: number, row: unknown[]): number => total + row.length, 0);
}

function countCells(value) {
  if (!is2DArray(value)) {
    return 0;
  }
  return value.reduce((total, row) => total + row.length, 0);
}

Source

src/lang/array/is2DArray.ts

23 September 2026

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

apps-script-utils 2.1.1 Help