Normative Conventions: pretend primitives aren't iterable (#152)

Co-authored-by: Kevin Gibbons <[email protected]>

Author: michaelficarra

normative-conventions.md

@@ -37,3 +37,11 @@ For the purposes of this guideline `-0` is considered to be an integral number (
 Some APIs intentionally round non-integral inputs, for example as an attempt to provide a best-effort behavior, rather than because the API fundamentally only makes sense with integers. This guideline does not apply to those cases.
 
 NB: This convention is new as of 2024, and most earlier parts of the language do not follow it.
+
+## Reject primitives in iterable-taking positions
+
+Any time an iterable or async-iterable value (a value that has a `Symbol.iterator` or `Symbol.asyncIterator` method) is expected, primitives should be treated as if they were not iterable. Usually, this will mean throwing a `TypeError`. If the user provides a primitive wrapper Object such as a String Object, however, it should be treated like any other Object.
+
+Although primitive Strings are default iterable (`String.prototype` has a `Symbol.iterator` method which enumerates code points), it is now considered a mistake to iterate a String without specifying whether the String is providing an abstraction over code units, code points, grapheme clusters, or something else.
+
+NB: This convention is new as of 2024, and most earlier parts of the language do not follow it. In particular, positional destructuring (both binding and assignment), array spread, argument spread, for-of loops, `yield *`, the `Set` and `AggregateError` constructors, `Object.groupBy`, `Map.groupBy`, `Promise.all`, `Promise.allSettled`, `Promise.any`, `Promise.race`, `Array.from`, the static `from` methods on typed array constructors, and `Iterator.from` (Stage 3 at time of writing) all accept primitives where iterables are expected.