Viewing: developer.mozilla.org

(iterable protocol) JavaScript for...of Array Map (Object )

[Symbol.iterator]() [Symbol.iterator] Symbol.iterator

[Symbol.iterator]()

for...of [Symbol.iterator]()

this

yield

(The iterator protocol)

next()

next(): 0 1 IteratorResult for...of false undefined TypeError ("iterator.next() returned a non-object value")

next()return()throw()IteratorResult

done

false done

true value

value

JavaScript done true

{ done: false, value: undefined }

done: true next() done: true

next next yield

return(value) throw(exception)

return(value): 0 1 IteratorResult value value done true next() return() value undefined
throw(exception): 0 1 IteratorResult done true exception Error throw() return/throw

: next()

[Symbol.iterator]() this

// 
const myIterator = {
  next() {
    // 
  },
  [Symbol.iterator]() {
    return this;
  },
};

API

const generatorObject = (function* () {
  yield 1;
  yield 2;
  yield 3;
})();

console.log(typeof generatorObject.next);
// "function"  next 

console.log(typeof generatorObject[Symbol.iterator]);
// "function"  [Symbol.iterator] 

console.log(generatorObject[Symbol.iterator]() === generatorObject);
// true  Symbol.iterator

Iterator.prototype [Symbol.iterator]() this

iterable[Symbol.iterator] Set.prototype[Symbol.iterator]()

[Symbol.asyncIterator]()

next(): 0 1 IteratorResult
return(value): 0 1 IteratorResult
throw(exception): 0 1 IteratorResult

API

StringArrayTypedArrayMapSetSegments Intl.Segmenter.prototype.segment() prototype [Symbol.iterator]() arguments DOM NodeList JavaScript ReadableStream API Symbol.asyncIterator

Iterator [Symbol.iterator]() { return this; } Iterator next()

console.log([][Symbol.iterator]());

Array Iterator {}
  [[Prototype]]: Array Iterator     ==> 
    next:  next()
    Symbol(Symbol.toStringTag): "Array Iterator"
    [[Prototype]]: Object           ==> 
      Symbol(Symbol.iterator):  [Symbol.iterator]()
      [[Prototype]]: Object         ==>  Object.prototype

API

const myObj = {};

new WeakSet(
  (function* () {
    yield {};
    yield myObj;
    yield {};
  })(),
).has(myObj); // true

for...of yield*

for (const value of ["a", "b", "c"]) {
  console.log(value);
}
// "a"
// "b"
// "c"

console.log([..."abc"]); // ["a", "b", "c"]

function* gen() {
  yield* ["a", "b", "c"];
}

console.log(gen().next()); // { value: "a", done: false }

[a, b, c] = new Set(["a", "b", "c"]);
console.log(a); // "a"

API done false return for...of break return

const obj = {
  [Symbol.iterator]() {
    let i = 0;
    return {
      next() {
        i++;
        console.log("Returning", i);
        if (i === 3) return { done: true, value: i };
        return { done: false, value: i };
      },
      return() {
        console.log("Closing");
        return { done: true };
      },
    };
  },
};

const [a] = obj;
// Returning 1
// Closing

const [b, c, d] = obj;
// Returning 1
// Returning 2
// Returning 3
// Already reached the end (the last call returned `done: true`),
// so `return` is not called
console.log([b, c, d]); // [1, 2, undefined]; the value associated with `done: true` is not reachable

for (const b of obj) {
  break;
}
// Returning 1
// Closing

for await...of yield* [Symbol.asyncIterator]() [Symbol.iterator]() for...of TypeError: x is not iterable

[Symbol.iterator]()
[Symbol.iterator]()
[Symbol.iterator]() next()

TypeError

const nonWellFormedIterable = { [Symbol.iterator]: 1 };
[...nonWellFormedIterable]; // TypeError: nonWellFormedIterable is not iterable
nonWellFormedIterable[Symbol.iterator] = () => 1;
[...nonWellFormedIterable]; // TypeError: [Symbol.iterator]() returned a non-object value
nonWellFormedIterable[Symbol.iterator] = () => ({});
[...nonWellFormedIterable]; // TypeError: nonWellFormedIterable[Symbol.iterator]().next is not a function

[Symbol.asyncIterator]() undefined null JavaScript [Symbol.iterator] [Symbol.asyncIterator]

next() next() TypeError

next() next() next() next()

return() return() next() done: true return()

return() return() TypeError return() return() return()

try {
  for (const value of iterable) {
    // 
  }
} catch (e) {
  // 
}

catch iterable next() return() for for

function* gen() {
  try {
    yield doSomething();
    yield doSomethingElse();
  } finally {
    cleanup();
  }
}

catch doSomething() doSomethingElse() gen finally finally next() return()

Iterator.from() (map(), filter(), take(), drop(), flatMap())yield* (for await...of, Array.fromAsync)

next()
return() return() { done: true, value: undefined } next() return() { done: true, value: undefined } yield*
yield* throw() yield* return() throw()

const myIterable = {
  *[Symbol.iterator]() {
    yield 1;
    yield 2;
    yield 3;
  },
};

console.log([...myIterable]); // [1, 2, 3]

function makeIterator(array) {
  let nextIndex = 0;
  return {
    next() {
      return nextIndex < array.length
        ? {
            value: array[nextIndex++],
            done: false,
          }
        : {
            done: true,
          };
    },
  };
}

const it = makeIterator(["yo", "ya"]);

console.log(it.next().value); // 'yo'
console.log(it.next().value); // 'ya'
console.log(it.next().done); // true

function idMaker() {
  let index = 0;
  return {
    next() {
      return {
        value: index++,
        done: false,
      };
    },
  };
}

const it = idMaker();

console.log(it.next().value); // 0
console.log(it.next().value); // 1
console.log(it.next().value); // 2
//

function* makeGenerator(array) {
  let nextIndex = 0;
  while (nextIndex < array.length) {
    yield array[nextIndex++];
  }
}

const gen = makeGenerator(["yo", "ya"]);

console.log(gen.next().value); // 'yo'
console.log(gen.next().value); // 'ya'
console.log(gen.next().done); // true

function* idMaker() {
  let index = 0;
  while (true) {
    yield index++;
  }
}

const it = idMaker();

console.log(it.next().value); // 0
console.log(it.next().value); // 1
console.log(it.next().value); // 2
//

class SimpleClass {
  #data;

  constructor(data) {
    this.#data = data;
  }

  [Symbol.iterator]() {
    // 
    // break 
    // 
    let index = 0;

    return {
      // : `next()` 
      // `[Symbol.iterator]()`  `this` 
      next: () => {
        if (index >= this.#data.length) {
          return { done: true };
        }
        return { value: this.#data[index++], done: false };
      },
    };
  }
}

const simple = new SimpleClass([1, 2, 3, 4, 5]);

for (const val of simple) {
  console.log(val); // 1 2 3 4 5
}

String

const someString = "hi";
console.log(typeof someString[Symbol.iterator]); // "function"

String 1

const iterator = someString[Symbol.iterator]();
console.log(`${iterator}`); // "[object String Iterator]"

console.log(iterator.next()); // { value: "h", done: false }
console.log(iterator.next()); // { value: "i", done: false }
console.log(iterator.next()); // { value: undefined, done: true }

[Symbol.iterator]()

// 
const someString = new String("hi");

someString[Symbol.iterator] = function () {
  return {
    //  "bye"
    next() {
      return this._first
        ? { value: "bye", done: (this._first = false) }
        : { done: true };
    },
    _first: true,
  };
};

[Symbol.iterator]()

console.log([...someString]); // ["bye"]
console.log(`${someString}`); // "hi"

URLSearchParams

const searchParams = new URLSearchParams(
  "deleteme1=value1&key2=value2&key3=value3",
);

// Delete unwanted keys
for (const [key, value] of searchParams) {
  console.log(key);
  if (key.startsWith("deleteme")) {
    searchParams.delete(key);
  }
}

// :
// deleteme1
// key3

key2 URLSearchParams deleteme1 1 key2 deleteme1 key3

Map

const myMap = new Map([
  ["deleteme1", "value1"],
  ["key2", "value2"],
  ["key3", "value3"],
]);

for (const [key, value] of myMap) {
  console.log(key);
  if (key.startsWith("deleteme")) {
    myMap.delete(key);
  }
}

// :
// deleteme1
// key2
// key3

Map

const tombstone = Symbol("tombstone");

class MyIterable {
  #data;
  constructor(data) {
    this.#data = data;
  }
  delete(deletedKey) {
    for (let i = 0; i < this.#data.length; i++) {
      if (this.#data[i][0] === deletedKey) {
        this.#data[i] = tombstone;
        return true;
      }
    }
    return false;
  }
  *[Symbol.iterator]() {
    for (let i = 0; i < this.#data.length; i++) {
      if (this.#data[i] !== tombstone) {
        yield this.#data[i];
      }
    }
  }
}

const myIterable = new MyIterable([
  ["deleteme1", "value1"],
  ["key2", "value2"],
  ["key3", "value3"],
]);
for (const [key, value] of myIterable) {
  console.log(key);
  if (key.startsWith("deleteme")) {
    myIterable.delete(key);
  }
}


ECMAScript 2027 LanguageSpecification # sec-iteration

MDN

2026827 MDN

GitHub