no-array-for-each: Add more reasoning to the docs

[Zamiell]

n/a

[Zamiell]

how long do PRs usually sit after being approved but before being merged?

[cmdcolin]

random quip: it would be cool to provide "examples" of what this text means e.g. a little code snippet showing the improved type narrowing, etc. as it's a little advanced (i'm just an onlooker of this repo)

[Zamiell]

The type narrowing difference is illustrated by the following code:

declare const foo: Foo | undefined;

if (foo === undefined) {
  return;
}

for (const element of array) {
  // type of `foo` is `Foo`
}

declare const foo: Foo | undefined;

if (foo === undefined) {
  return;
}

array.forEach((element) => {
  // type of `foo` is `Foo | undefined` (because we passed a function boundary)
});

The variable mutation difference is illustrated by the following code:

function countArray(array: number[]) {
  let count = 0;

  for (const element of array) {
    count += element;
  }

  return count;
}

function countArray(array: number[]) {
  let count = 0;

  array.forEach((element) => {
    count += element;
  });

  return count; // lint error: count is never modified (because we passed a function boundary)
}

[cmdcolin]

excellent, thanks for the demo!