Iterator.from()
===============

**Experimental:** **This is an experimental technology**  
Check the Browser compatibility table carefully before using this in production.

The **`Iterator.from()`** static method creates a new `Iterator` object from an iterator or iterable object.

Syntax
------


```js
from(object)
```

### Parameters

`object`

An object that implements the iterable protocol or the iterator protocol.

### Return value

If `object` is an iterable, its `@@iterator` method is called to obtain the iterator. Otherwise, `object` is assumed to be an iterator. If the iterator is already `instanceof` `Iterator` (which means it has `Iterator.prototype` in its prototype chain), it is returned directly. Otherwise, a new `Iterator` object is created that wraps the original iterator.

Description
-----------

This method exists to convert custom iterators, probably exported by libraries, to proper iterators. All iterator objects returned by `Iterator.from()` inherit from a common prototype object, which has the following methods:

`next()`

Calls the underlying iterator's `next()` method and returns the result.

`return()`

Calls the underlying iterator's `return()` method and returns the result, or returns `{ value: undefined, done: true }` if the underlying iterator doesn't have a `return()` method.

Examples
--------

### Converting an iterable to a proper iterator

Because `obj` is already an iterable that returns a proper iterator when its `@@iterator` method is called, `Iterator.from(obj)` returns the same iterator.


```js
const iterator = (function\* () {
  yield 1;
  yield 2;
  yield 3;
})();

const obj = {
  [Symbol.iterator]() {
    return iterator;
  },
};

const iterator2 = Iterator.from(obj);
console.log(iterator2 === iterator); // true
```


Because `obj2` is an iterable that returns a non-proper iterator when its `@@iterator` method is called, `Iterator.from(obj2)` returns a new iterator that wraps the original iterator.


```js
const iterator = {
  current: 0,
  next() {
    return { value: this.current++, done: false };
  },
};

const obj2 = {
  [Symbol.iterator]() {
    return iterator;
  },
};

const iterator2 = Iterator.from(obj2);
console.log(iterator2 === iterator); // false
console.log(iterator2.next()); // { value: 0, done: false }
console.log(iterator.next()); // { value: 1, done: false }
```

### Converting an iterator to a proper iterator

Because `obj` is already a proper iterator, `Iterator.from(obj)` returns itself.


```js
const obj = (function\* () {
  yield 1;
  yield 2;
  yield 3;
})();

const iterator = Iterator.from(obj);
console.log(iterator === obj); // true
```


Because `obj2` is a non-proper iterator, `Iterator.from(obj2)` returns a new iterator that wraps the original iterator.


```js
const obj2 = {
  current: 0,
  next() {
    return { value: this.current++, done: false };
  },
};

const iterator = Iterator.from(obj2);
console.log(iterator === obj2); // false
console.log(iterator.next()); // { value: 0, done: false }
console.log(obj2.next()); // { value: 1, done: false }
```

Specifications
--------------

| Specification |
| --- |
| Iterator Helpers # sec-iterator.from |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Polyfill of `Iterator.from` in `core-js`
* `Iterator`
* `Array.from()`