non2DArray

function non2DArray<T>(arr: T | Array<Array<unknown>>): arr is T;

non2DArray(value) is the same test as !is2DArray(value). The prefix exists so that a guard clause reads as a sentence rather than as a negation — see Validation conventions.

An empty array qualifies as "not two-dimensional", because is2DArray requires at least one row.

A caveat on types: the guard is declared as a type predicate, but it only narrows usefully when the value's own type already names unknown[][] as one of its cases. In the branch where the value is a matrix, TypeScript is left with never rather than a matrix type, so reach for is2DArray or require2DArray when the matrix has to be used after the check. As a plain boolean answer, non2DArray is exact in every case.

Parameters

Parameter	Type	Description
`arr`	`T \\| Array<Array<unknown>>`	The value to check.

Returns

boolean — true if the value is not a non-empty array of arrays; otherwise false.

In TypeScript the guard narrows arr to T inside the branch.

Examples

What counts as not two-dimensional

non2DArray([1, 2]); // => true — flat
non2DArray([]); // => true — no rows
non2DArray("abc"); // => true
non2DArray([[1], [2]]); // => false

Reporting why a value was rejected

/**
 * Validates the shape of a value before it reaches `setValues`, and returns
 * the reason it was rejected rather than throwing.
 */
export function validateShape(rows: unknown): string | null {
  if (non2DArray(rows)) {
    return "Expected a matrix: a non-empty array of rows.";
  }

  if (nonConsistent2DArray(rows)) {
    return "Every row must have the same number of columns.";
  }

  return null;
}

function validateShape(rows) {
  if (non2DArray(rows)) {
    return "Expected a matrix: a non-empty array of rows.";
  }
  if (nonConsistent2DArray(rows)) {
    return "Every row must have the same number of columns.";
  }
  return null;
}

Source

src/lang/array/non2DArray.ts

23 September 2026

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

apps-script-utils 2.1.1 Help