JS: Interface

By Xah Lee. Date: . Last updated: .

New in ES2015.

What's JavaScript interface?

  1. An interface is a set of property keys whose associated values match a specific specification.
  2. Any object that has all the properties (or inherited) as described by an interface’s spec, is said to conform to that interface.

Note: by definition, there can be many objects that conform to the same interface.

Note: by definition, a object may conform to multiple 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 TutorialA 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"Either true or false.This 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.

Reference

ECMAScript 2015 §Control Abstraction Objects#sec-common-iteration-interfaces

Iterable / Iterator / Generator Topic

  1. JS: Interface
  2. JS: Iterable
  3. JS: Iterator
  4. JS: for-of Loop
  5. JS: Generator Function
  6. JS: Generator
Like what you read? Buy JavaScript in Depth