Array.isArray type narrows to any[] for ReadonlyArray<T>

TypeScript Version: 2.4.1

Code

declare interface T {
  foo: string;
}

const immutable: T | ReadonlyArray<T> = [];

if (Array.isArray(immutable)) {
  const x = immutable; // Any[]  - Should be ReadonlyArray<T>
} 

const mutable: T | Array<T> = [];

if (Array.isArray(mutable)) {
  const x = mutable; // T[]
}

Expected behavior: Should type narrow to ReadonlyArray<T>, or at the very least T[].

Actual behavior: Narrows to any[]. Doesn't trigger warnings in noImplicitAny mode either.

If you add the following declaration to overload the declaration of isArray():

interface ArrayConstructor {
    isArray(arg: ReadonlyArray<any> | any): arg is ReadonlyArray<any>    
}

the post-checked mutable is still narrowed to T[] and the post-checked immutable is narrowed to ReadonlyArray<T> as desired.

I'm not sure if this or similar would be an acceptable addition to the standard typing libraries or not, but you can at least use it yourself.

Joe Calzaretta (@jcalz)

Joe Calzaretta (@jcalz) yes, I think these overloads should be in the standard library. There are a few other scenarios where ReadonlyArray isn't accepted where it should be (for example Array.concat).

The same narrowing problem also exists for this check:

if (immutable instanceof Array) {
  const x = immutable; // Any[]  - Should be ReadonlyArray<T>
}

I'm not sure if there exists a similar workaround for this.

I would probably do this if I wanted a workaround:

interface ReadonlyArrayConstructor  {
    new(arrayLength?: number): ReadonlyArray<any>;
    new <T>(arrayLength: number): ReadonlyArray<T>;
    new <T>(...items: T[]): ReadonlyArray<T>;
    (arrayLength?: number): ReadonlyArray<any>;
    <T>(arrayLength: number): ReadonlyArray<T>;
    <T>(...items: T[]): ReadonlyArray<T>;
    isArray(arg: any): arg is ReadonlyArray<any>;
    readonly prototype: ReadonlyArray<any>;
}
const ReadonlyArray = Array as ReadonlyArrayConstructor;

And then later

if (ReadonlyArray.isArray(immutable)) {
  const x = immutable; // ReadonlyArray<T>
} 
if (immutable instanceof ReadonlyArray) {
  const x = immutable; //  ReadonlyArray<T>
}

but of course, since at runtime there's no way to tell the difference between ReadonlyArray and Array, you would have to be careful to use the right one in the right places in your code. ¯\_(ツ)_/¯

Vidar Tonaas Fauske (@vidartf)

Vidar Tonaas Fauske (@vidartf) As instanceof works at runtime, I'm not sure that should narrow to ReadonlyArray. You're asking if the runtime representation of that is an array, which is true. So I'd expect it to narrow to Array<T>, not ReadonlyArray<T>.

Jinder Sidhu (@jinder)

Jinder Sidhu (@jinder) I didn't state it explicitly, but my code was meant to be based on yours (same variables and types), so it should already know that it was T | ReadonlyArray<T>. As such, instanceof should narrow it to ReadonlyArray<T>.

What is the best workaround here ?
I just ended up with ugly type assertion:

function g(x: number) {}

function f(x: number | ReadonlyArray<number>) {
    if (!Array.isArray(x)) { 
        g(x as number); // :(
    }
}

I think this is fixed in 3.0.3.

Adrian Heine né Lang (@adrianheine)

Adrian Heine né Lang (@adrianheine) doesn't seem to be for me.

Oh, yeah, I was expecting the code in the original issue to not compile, bu that's not even the issue.

let command: readonly string[] | string;

let cached_command: Record<string, any>;

if (Array.isArray(command))
{

}
else
{
	cached_command[command] = 1;
	// => Error: TS2538: Type 'readonly string[]' cannot be used as an index type.
}

Aleksey Lagashkin (@aleksey-l)

Temporary solution from Aleksey Lagashkin (@aleksey-l) (on stackoverflow) until the bug is fixed:

declare global {
    interface ArrayConstructor {
        isArray(arg: ReadonlyArray<any> | any): arg is ReadonlyArray<any>
    }
}

Just adding my 2c here that I would really appreciate for this to work natively. I think its a little unintuitive that Array.isArray doesn't catch a readonly [], although I understand that its not as simple as a one line fix :)

here my solution

declare global {
	interface ArrayConstructor {
		isArray( arg: Any ): arg is readonly Any[];
	}
}

enjoy:
playground

Thanks for that suggestion 👍 , but I've seen that workaround above in this thread.

I'd prefer to not resort to a workaround and rather use a neater solution in-which the in-built .isArray method handles this use case.

Our team just ran into this issue with the readonly keyword as well. We would very much appreciate for this to work natively.

Remove any from Array.isArray, fix violations (#6760)

Another workaround:

function isReadonlyArray<T, Rest>(value: readonly T[] | Rest): value is readonly T[] {
  return Array.isArray(value);
}

// or just
const isArray = Array.isArray as <T, Rest>(value: readonly T[] | Rest) => value is readonly T[];

playground

Another workaround:

function isReadonlyArray<T, Rest>(value: readonly T[] | Rest): value is readonly T[] {
return Array.isArray(value);
}

// or just
const isArray = Array.isArray as <T, Rest>(value: readonly T[] | Rest) => value is readonly T[];
playground

Funny timing, I just stumbled upon this issue about 6 hours after your comment, here’s an alternative version of your workaround I ended up using:

const isArray = Array.isArray as <T>(value: T) => value is Extract<T, readonly unknown[]>;

This also works with unknown you don't want to use any or type assertions (due to linting rules or personal preference)

declare global {
  interface ArrayConstructor {
    isArray(arg: unknown): arg is readonly unknown[];
  }
}

Imo this is the cleanest option because it only augments the type without declaring new variables, so output stays the same..

cahnory

I believe cahnory solution is the best one so far and it should be in the standard library

(arg: unknown): arg is readonly unknown[]

This also works with unknown you don't want to use any or type assertions (due to linting rules or personal preference)

declare global {
interface ArrayConstructor {
isArray(arg: unknown): arg is readonly unknown[];
}
}

Imo this is the cleanest option because it only augments the type without declaring new variables, so output stays the same..

I like your version better for its simplicity.

The only minor difference I noticed is that if the input type is statically known to be non-array, the true branch won’t narrow to never, but instead to V & readonly unknown[].

That said, I personally avoid augmenting standard library types and prefer creating a dedicated helper. But this is mostly a matter of preference 😉

fix(types): ensure Array.isArray will not widen readonly arrays to any

Sigurd Spieckermann (@sisp)

I've submitted a minimal fix for this in #63609 — a single additive overload in es5.d.ts that preserves readonly when the input type already carries it. Unlike approaches that change the narrowing result for unknown (which Sigurd Spieckermann (@sisp) correctly identified as a breaking change), this overload only matches when the input is already typed as readonly any[] | T, so unknown and mutable arrays continue to narrow exactly as they do today. The total change is one line in the lib plus a test file.

Dai Luo (@daishuge)

Dai Luo (@daishuge): I left a comment on your PR. Unfortunately, your fix would break a lot of existing code.

fix(config): fifth codex round — deep-readonly metadata, integer freq…

Navigation Menu

Repository navigation

Array.isArray type narrows to any[] for ReadonlyArray<T> #17002

46 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Array.isArray type narrows to any[] for ReadonlyArray<T> #17002

Description

Activity

jcalz commented on Jul 7, 2017

jinder commented on Jul 7, 2017

vidartf commented on Jul 10, 2017

jcalz commented on Jul 10, 2017

jinder commented on Jul 10, 2017

vidartf commented on Jul 10, 2017

NN--- commented on Sep 20, 2017

adrianheine commented on Sep 17, 2018

jinder commented on Sep 18, 2018

adrianheine commented on Sep 18, 2018

bluelovers commented on May 17, 2019

paulmiu commented on May 22, 2019

46 remaining items

A-EbrahimRSA commented on Apr 4, 2025

jonlepage commented on Apr 6, 2025

A-EbrahimRSA commented on Apr 7, 2025

oconnorjoseph commented on Apr 9, 2025

spalt08 commented on Jan 22, 2026

cahnory commented on Jan 22, 2026

niklasholm commented on Feb 25, 2026

slztfn commented on Mar 17, 2026

cahnory commented on Mar 18, 2026

daishuge commented on Jul 5, 2026

anderson-pete commented on Jul 6, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions