docs: describe Array#forEach anti patterns

[keithamus]

Closes #86.

This describes in more detail why we discourage forEach, instead preferring for...of.

/cc @koddsson @zeke

[muan]

I believe @zeke was also right with regards to async functions in that forEach is blocking while for...of isn't. I vaguely remember that being the reason. cc @dgraham

[dgraham]

async function doSomething(x) { await ... }

// Probably doesn't do what you expect.
items.forEach(item => { await doSomething(item })

// vs

// Blocks the loop as expected.
for (const item of items) {
  await doSomething(item)
}

[keithamus]

This is a syntax error:

items.forEach(item => { await doSomething(item) })

This will await, but the async function itself is not awaited because forEach does nothing with the return value:

items.forEach(async item => { await doSomething(item) })

This is how you'd have to refactor this to be async:

await Promise.all(items.map(async item => { await doSomething(item) }))

I'll add this as an example in the Flexibility heading.

[zeke]

Wow thanks for taking the time to document this. Looks good. 👍