Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Narrowing and Type Guards

Array.isArray and type narrowing

Reference for Array.isArray as a TypeScript type guard: any[] results, readonly arrays, narrowing unknown, string-or-array unions and the readonly gotcha.

Array.isArray(value) is declared in TypeScript's library as a type guard: isArray(arg: any): arg is any[]. When it returns true, the argument is narrowed to an array type. When it returns false, array types are removed from a union.

You need it because typeof [] === "object", so typeof cannot separate arrays from other objects. It also works across realms (iframes, workers), where instanceof Array fails.

TypeScript
function toList(x: string | string[]): string[] {
  return Array.isArray(x) ? x : [x];
}

Try it

TypeScript One value or a list of values

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TypeScript Narrowing unknown

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TypeScript The readonly array gotcha

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

Syntax

TypeScript
Array.isArray(value): value is any[]
Part Description
value Any value.
Returns true for real arrays (including subclasses and proxies of arrays). false for typed arrays, array-likes, strings and iterables.

How the result narrows:

Declared type True branch
string | string[] string[]
unknown any[]
T | T[] T[], plus T & any[] when T is a type parameter
readonly string[] | string readonly string[] in the true branch, but the false branch is still string | readonly string[]

Edge cases:

  • Narrowing unknown gives any[], so elements are any. Check each element before use, or use a guard with a better element type.
  • A readonly array type is not removed in the false branch (the last example shows the resulting TS2339 error). Test with typeof x === "string" instead, or write a guard whose predicate is x is readonly unknown[].

Usage notes

  • Why not instanceof Array? It fails for arrays from another realm, such as an iframe or a worker message. Array.isArray does not.
  • Typed arrays and array-likes. Array.isArray(new Uint8Array()) is false. Test those with ArrayBuffer.isView or instanceof.
  • Elements are not checked. The guard proves "it is an array", nothing about what it holds. string | number[] is fine, but a unknown[] of unknown items needs a per-element check.
  • Better element types. To narrow to string[], write a custom guard such as (x: unknown): x is string[] => Array.isArray(x) && x.every((i) => typeof i === "string").
  • Tuples. A tuple type in a union is an array type and is kept in the true branch.