get Promise[@@species]

The Promise[@@species] accessor property returns the constructor used to construct return values from promise methods.

Warning: The existence of @@species allows execution of arbitrary code and may create security vulnerabilities. It also makes certain optimizations much harder. Engine implementers are investigating whether to remove this feature. Avoid relying on it if possible.

Syntax

Promise[Symbol.species]

Return value

The value of the constructor (this) on which get @@species was called. The return value is used to construct return values from promise chaining methods that create new promises.

Description

The @@species accessor property returns the default constructor for Promise objects. Subclass constructors may override it to change the constructor assignment. The default implementation is basically:

// Hypothetical underlying implementation for illustration
class Promise {
  static get [Symbol.species]() {
    return this;
  }
}

Because of this polymorphic implementation, @@species of derived subclasses would also return the constructor itself by default.

class SubPromise extends Promise {}
SubPromise[Symbol.species] === Promise; // true

When chaining promise methods like then(), finally(), etc., the instance's constructor[@@species] will be accessed. The returned constructor will be used to construct the return value of the promise method.

Examples

Species in ordinary objects

The Symbol.species property returns the default constructor function, which is the Promise constructor for Promise.

Promise[Symbol.species]; // [Function: Promise]

Species in derived objects

In an instance of a custom Promise subclass, such as MyPromise, the MyPromise species is the MyPromise constructor. However, you might want to override this, in order to return parent Promise objects in your derived class methods.

class MyPromise extends Promise {
  // Override MyPromise species to the parent Promise constructor
  static get [Symbol.species]() {
    return Promise;
  }
}

By default, promise methods would return promises with the type of the subclass.

class MyPromise extends Promise {
  someValue = 1;
}

console.log(MyPromise.resolve(1).then(() => {}).someValue); // 1

By overriding @@species, the promise methods will return the base Promise type.

class MyPromise extends Promise {
  someValue = 1;
  static get [Symbol.species]() {
    return Promise;
  }
}

console.log(MyPromise.resolve(1).then(() => {}).someValue); // undefined

Specifications

No specification found

No specification data found for javascript.builtins.Promise.@@species.
Check for problems with this page or contribute a missing spec_url to mdn/browser-compat-data. Also make sure the specification is included in w3c/browser-specs.

Browser compatibility

No compatibility data found for javascript.builtins.Promise.@@species.
Check for problems with this page or contribute missing data to mdn/browser-compat-data.

See also