Add Array.isArray improvement

readme.md

@@ -256,6 +256,43 @@ const validate = (input: unknown) => {
 };
 ```
 
+### Make `Array.isArray` correctly narrow with `ReadonlyArray<Item>`
+
+```ts
+import "@total-typescript/ts-reset/array-includes";
+```
+
+This rule improves on TypeScript's default `Array.isArray` behaviour. Without this rule enabled, TypeScript will not include `ReadonlyArray<Item>` when narrowing Array types.
+
+```ts
+// BEFORE
+function makeArray(input: string | ReadonlyArray<string> | Array<string>) {
+  if (Array.isArray(input)) {
+    return input;
+  }
+  return [input];
+}
+
+type Result = ReturnType<typeof makeArray>; // (string | readonly string[])[]
+```
+
+This is almost definitely not what the user intended! While it works correctly at run-time (since JS has no concept of ReadonlyArray), the inferred types are very incorrect.
+
+```ts
+// AFTER
+import "@total-typescript/ts-reset/array-includes";
+
+function makeArray(input: string | ReadonlyArray<string> | Array<string>) {
+  // Array.isArray now
+  if (Array.isArray(input)) {
+    return input;
+  }
+  return [input];
+}
+
+type Result = ReturnType<typeof makeArray>; // string[]
+```
+
 ## Rules we won't add
 
 ### `Object.keys`/`Object.entries`

src/entrypoints/is-array.d.ts

@@ -1,3 +1,3 @@
 interface ArrayConstructor {
-  isArray(arg: any): arg is unknown[];
+  isArray(arg: any): arg is ReadonlyArray<unknown> | Array<unknown>;
 }

src/tests/is-array.ts

@@ -4,7 +4,9 @@ doNotExecute(() => {
   const maybeArr = [1, 2, 3] as unknown;
 
   if (Array.isArray(maybeArr)) {
-    type tests = [Expect<Equal<typeof maybeArr, unknown[]>>];
+    type tests = [
+      Expect<Equal<typeof maybeArr, unknown[] | readonly unknown[]>>
+    ];
   }
 });
 
@@ -15,3 +17,17 @@ doNotExecute(() => {
     type tests = [Expect<Equal<typeof arrOrString, string[]>>];
   }
 });
+
+doNotExecute(async () => {
+  function makeArray<Item>(input: Item | ReadonlyArray<Item> | Array<Item>) {
+    if (Array.isArray(input)) {
+      return input;
+    }
+    return [input];
+  }
+
+  const [first] = makeArray([{ a: "1" }, { a: "2" }, { a: "3" }] as const);
+
+  // No error!
+  first.a;
+});