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.
function toList(x: string | string[]): string[] { return Array.isArray(x) ? x : [x]; }
Try it
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.
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.
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
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
unknowngivesany[], so elements areany. Check each element before use, or use a guard with a better element type. - A
readonlyarray type is not removed in the false branch (the last example shows the resulting TS2339 error). Test withtypeof x === "string"instead, or write a guard whose predicate isx 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.isArraydoes not. - Typed arrays and array-likes.
Array.isArray(new Uint8Array())isfalse. Test those withArrayBuffer.isVieworinstanceof. - Elements are not checked. The guard proves "it is an array", nothing about what it holds.
string | number[]is fine, but aunknown[]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.