Repository: TypeScript
Issue: Add `--strictObjectIterables` (bikeshed): exclude primitive (`string`) from `Iterable` types
Labels: Suggestion,Needs Proposal

### 🔍 Search Terms

"iterable object", "string"

### ✅ Viability Checklist

- [X] This wouldn't be a breaking change in existing TypeScript/JavaScript code
- [X] This wouldn't change the runtime behavior of existing JavaScript code
- [X] This could be implemented without emitting different JS based on the types of the expressions
- [X] This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
- [X] This isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
- [X] This feature would agree with the rest of our Design Goals: https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals

### ⭐ Suggestion

At the TC39 meeting in 2024-07, it was decided that `Iterable` expects objects.

> ## 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.

https://github.com/tc39/how-we-work/blob/main/normative-conventions.md#reject-primitives-in-iterable-taking-positions

To follow this decision, the `Iterable` and `string` types should be separated, and APIs that accept both types should be required to explicitly specify `Iterable<any> | string`. Since this would be a breaking change, how about adding a new `--strictObjectIterables` (bikeshed) option?

In practice, the upcoming `ReadableStream.from` will accept `Iterable<any>` and `AsyncIterable<any>`, but will be restricted to objects. https://github.com/whatwg/streams/pull/1310

### 📃 Motivating Example

Enabling the `--strictObjectIterables` option raises a type error in the following example:

```ts
const iterable: Iterable<any> = "string";
```

### 💻 Use Cases

1. What do you want to use this for?

    Used for `ReadableStream.from` and other APIs to be added in the future.

2. What shortcomings exist with current approaches?

    `Iterable` object and `string` are not distinguished by default.

3. What workarounds are you using in the meantime?

    Maybe `Iterable<any> & object` can reject `string`.