Collection-agnostic APIs
A utility needs to consume arrays, sets, maps, strings, or typed arrays through one parameter.
TypeScript · Interface
Iterable
Iterable<T> describes values that implement Symbol.iterator and yield elements of type T. It lets functions accept arrays and other iterable collections through one generic type.
How it works
Iterable<T> describes a value whose [Symbol.iterator]() method produces values of type T. It lets APIs accept arrays and other iterable built-ins uniformly, while operations such as spread and for...of consume the iterable's yielded values.
Syntax
Iterable<T>Parameters
| Name | Type | Description |
|---|---|---|
T | type parameter | The element type yielded by the iterable. |
Returns
An iterable value yields elements of type T; the page's example converts those elements to T[].
Key points
- The defining requirement is a
Symbol.iteratorimplementation. - Common built-in iterables include arrays, maps, sets, strings, and typed arrays.
- Use
Iterable<T>when an API should accept a broad family of iterable inputs. - The iterator method supplies the values consumed by iteration.
- A
for...ofloop starts iteration through the object's symbol-keyed iterator method. for...ofis value-oriented, unlike key-oriented property enumeration.
Common mistakes
- With an ES5 target,
for...ofover non-array iterables is rejected even when those values implementSymbol.iterator; use an appropriate target or iteration configuration.
Example: Accepting an iterable
function toArray<T>(items: Iterable<T>): T[] {
return [...items];
}
const values = toArray(new Set([1, 2, 3]));
console.log(values);The function accepts any iterable and materializes its yielded values into a typed array.
When to use it
Conversion to arrays
A function materializes any iterable into a new array with its element type preserved.
Value iteration
A loop should consume yielded values rather than object property names.
Interview questions
QWhat does Iterable<T> mean in TypeScript?
Iterable<T> represents a value that can be iterated and yields elements of type T. Arrays, maps, sets, strings, and several typed arrays provide the required Symbol.iterator implementation.
Follow-up: How does for...of differ from for...in? for...of reads iterable values, whereas for...in enumerates property keys.
QHow does an object qualify as iterable?
The iterable protocol is based on a Symbol.iterator property whose function returns the sequence's iterator. A generic parameter records the type of each value produced by that sequence.
Follow-up: What does the iterator method itself return? It returns the iterator used to obtain the values being traversed.
QWhy use Iterable<T> in a public API?
A function parameter typed as Iterable<T> can accept different iterable collections without requiring an array specifically. For example, spreading the parameter into an array preserves the element type as T.
Follow-up: Why might a library prefer this parameter type? It supports the minimal protocol needed by consumers and avoids unnecessarily restricting callers to one collection representation.
Related
IteratorIterableIteratorGeneratorSymbol.iteratorfor...of