JS: Interface

By Xah Lee. Date: . Last updated: .

New in ES2015.

Purpose of JavaScript Interface

JavaScript interface is the underlying mechanism for how JavaScript “iterable object” works.

Note: iterable object allow for-of loop to go thru a object, with potentially infinite number of items. [see JS: for-of Loop]

What's JavaScript interface?

An interface is a spec for a set of property keys and values.

Any object that has all the properties (or inherited) as described by an interface’s spec, is said to have (conform to) that interface.

Note: by definition, many objects can have the same interface.

Note: by definition, a object can have many interfaces.

When a object confoms to interface X, we say that the object is “X object” or just X. For example, a object that conforms to the iterable interface is called “iterable object”, or just “iterable”.

There are 3 interfaces defined by the JavaScript spec:

  1. Iterable interface
  2. Iterator interface
  3. IteratorResult interface

Iterable Interface

Iterable Interface
PropertyValueRequirement
Symbol.iterator [see JS: Symbol Tutorial]A function that returns a iterator object.The returned object must conform to the Iterator interface.

[see JS: Iterable]

Iterator Interface

Iterator Interface
PropertyValueRequirement
"next"A function that returns an IteratorResult object. The returned object must conform to the IteratorResult interface. If a previous call to the "next" method of an Iterator has returned an IteratorResult object whose "done" property is true, then all subsequent calls to the "next" method of that object should also return an IteratorResult object whose "done" property is true. However, this requirement is not enforced.

The following are optional:

Iterator Interface Optional Property Keys
PropertyValueRequirement
"return" A function that returns an IteratorResult object. The returned object must conform to the IteratorResult interface. Invoking this method notifies the Iterator object that the caller does not intend to make any more "next" method calls to the Iterator. The returned IteratorResult object will typically have a "done" property whose value is true, and a value property with the value passed as the argument of the return method. However, this requirement is not enforced.
"throw" A function that returns an IteratorResult object. The returned object must conform to the IteratorResult interface. Invoking this method notifies the Iterator object that the caller has detected an error condition. The argument may be used to identify the error condition and typically will be an exception object. A typical response is to throw the value passed as the argument. If the method does not throw, the returned IteratorResult object will typically have a "done" property whose value is true.

[see JS: Iterator]

IteratorResult Interface

IteratorResult Interface
PropertyValueRequirement
"done"true or falseThis is the result status of an iterator next method call. If the end of the iterator was reached, "done" is true. If the end was not reached "done" is false and a "value" is available. If a "done" property (either own or inherited) does not exist, it is consider to have the value false.
"value"Any JavaScript value.If "done" is false, this is the current iteration element value. If "done" is true, this is the return value of the iterator, if it supplied one. If the iterator does not have a return value, value is undefined. In that case, the value property may be absent from the conforming object if it does not inherit an explicit value property.

JS Iterable ⭐

  1. Interface
  2. Iterable
  3. Iterator
  4. Iterator Prototype
  5. for-of Loop
  6. Spread Operator
  7. Generator
  8. Generator Function
Like it? Help me by telling your friends. Or, Put $5 at patreon.

Or, Buy JavaScript in Depth

If you have a question, put $5 at patreon and message me.

Web Dev Tutorials