require(["esri/core/promiseUtils"], function(promiseUtils) { /* code goes here */ });
Object: esri/core/promiseUtils
Since: ArcGIS API for JavaScript 4.2

Various utilities and convenience functions for working with promises.

Method Overview

NameReturn TypeSummaryObject
Promise

Convenience utility method for creating and resolving a promise.

more details
more detailspromiseUtils
Promise|Object

Convenience utility method to wait for a number of promises to either resolve or reject.

more details
more detailspromiseUtils
Promise

A convenience utility method for filtering an array of values using an asynchronous predicate function.

more details
more detailspromiseUtils
Promise

Convenience utility method to create a promise that has been rejected with a provided error value.

more details
more detailspromiseUtils
Promise

Convenience utility method to create a promise that will be resolved with a provided value.

more details
more detailspromiseUtils

Method Details

create(executor){Promise}

Convenience utility method for creating and resolving a promise.

Parameter:
executor Executor

A function that will be called with two methods, resolve and reject.

Returns:
TypeDescription
PromiseA promise that will be fulfilled by the executor.
Examples:
function fetchImage(url) {
  return promiseUtils.create(function(resolve, reject){
    const image = document.createElement("img");
    image.onload = function() {
      image.load = image.onerror = null;
      resolve(image);
    };

    image.onerror = function() {
      image.load = image.onerror = null;
      reject(new Error("Error while loading the image"));
    }

    image.src = url;
  });
}

fetchImage(".........")
  .then(function(image){
    console.log(image);
  });
// Load multiple modules conditionally
require([
  "esri/core/promiseUtils"
], function( promiseUtils ) {
  // load modules based on whether a user selects
  // a UI option to apply class breaks to a layer
  if (classBreaksSelected) {
    return promiseUtils.create(function(resolve, reject) {
      require([ "esri/renderers/ClassBreaksRenderer" ], resolve);
    }).then(function(ClassBreaksRenderer) {
      // Create renderer and apply it to the desired layer

    });
  }
});
eachAlways(promises){Promise|Object}

Convenience utility method to wait for a number of promises to either resolve or reject. The resulting promise resolves to an array of result objects containing the promise and either a value if the promise resolved, or an error if the promise rejected.

Parameter:
promises Promise[]|Object

Array of promises, or object where each property is a promise.

Returns:
TypeDescription
Promise | ObjectIf called with an array of promises, resolves to an array of result objects containing the original promise and either a value (if the promise resolved) or an error (if the promise rejected). If called with an object where each property is a promise, then resolves to an object with the same properties where each property value is a result object.
Example:
// Query for the number of features from
// multiple feature layers
function queryLayerFeatureCount(whereClauses) {
  // pass each whereClause item into callback function
  return promiseUtils.eachAlways(whereClauses.map(function (whereClause) {
    return layer.queryFeatureCount(whereClause);
  }));
}

queryLayerFeatureCount(whereClauses).then(function(eachAlwaysResults) {
   eachAlwaysResults.forEach(function(result) {
     // If a Promise was rejected, you can check for the rejected error
     if (result.error) {
       console.log("There was an error in your query.", result.error);
     }
     // The results of the Promise are returned in the value property
     else {
       console.log("The number of features are: " + result.value);
     }
   });
});
filter(input, predicate){Promise}

A convenience utility method for filtering an array of values using an asynchronous predicate function.

Parameters:
input Array

The array of input values to filter.

A predicate function returning a promise. Only array entries for which the returned promise contains true are kept.

Returns:
TypeDescription
PromiseA promise containing an array of values that passed the predicate check.
reject(error){Promise}

Convenience utility method to create a promise that has been rejected with a provided error value.

Parameter:
error Object
optional

The error to reject the resulting promise with.

Returns:
TypeDescription
PromiseA promise which is rejected with the provided error.
Example:
if (!data || !data.url) {
  return promiseUtils.reject(new Error("url is a required options property"));
}
resolve(value){Promise}

Convenience utility method to create a promise that will be resolved with a provided value.

Parameter:
value *
optional

The value to resolve the resulting promise with.

Returns:
TypeDescription
PromiseA promise which is resolved with the provided value.
Example:
// createGraphics will return a Promise that
// resolves to graphics array
function createGraphics() {
  var graphics = geoJson.features.map(function(feature, i) {
     return new Graphic({
       geometry: new Point({
         x: feature.geometry.coordinates[0],
         y: feature.geometry.coordinates[1]
       }),

       attributes: {
         ObjectID: i,
         title: feature.properties.title
       }
     });
  });

  return promiseUtils.resolve(graphics);
}

Type Definitions

EachAlwaysResult Object

The result object for a promise passed to promiseUtils.eachAlways.

Properties:
promise Promise

The promise that has been fulfilled.

value *
optional

The value with which the promise resolved. Defined only if the promise resolved.

error *
optional

The error with which the promise rejected. Defined only if the promise rejected.

Executor(resolve, reject)

A function that defines how a promise created in create() is resolved and rejected.

Parameters:

A function that will fulfill the promise.

A function that will handle the rejection of the promise.

FilterPredicateCallback(value, index){Promise}

Callback to be called for each entry of an array to be filtered.

Parameters:
value *

The value of the array entry.

index Number

The index of the entry within the array.

Returns:
TypeDescription
PromiseA promise that resolves to a boolean value, indicating whether the entry should be kept in the filtered array.
RejectCallback(error)

A function that will reject the promise created in create().

Parameter:
error *
optional

The error with which the promise rejected. Defined only if the promise is rejected.

ResolveCallback(value)

A function that will resolve the promise created in create().

Parameter:
value *|Promise<*>
optional

The value with which the promise resolved. Defined only if the promise is fulfilled.

API Reference search results

NameTypeModule
Loading...