Skip To ContentArcGIS for DevelopersSign In Dashboard
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
Function

A utility for ensuring an input function is not simultaneously invoked more than once at a time.

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

    });
  }
});
debounce(callback){Function}static
Since: ArcGIS API for JavaScript 4.12

A utility for ensuring an input function is not simultaneously invoked more than once at a time. This is useful for highly interactive applications such as those that execute statistic queries on mouse-move or mouse-drag events. Rather than execute the query for each such event, you can "debounce", or cancel the function execution, until the previous execution of the same function call finishes. This improves the performance and user experience of such applications.

Parameter:
callback Function

A function to prevent executing during the execution of a previous call to the same function. This is typically a function that may be called on mouse-move or mouse-drag events.

Returns:
TypeDescription
FunctionA function with the same signature as the callback.
See also:
Example:
// Queries a layer for the count of features that intersect a
// 1 km buffer of the pointer location. The debounce() method
// prevents the updateStatistics function from executing before
// a previous invocation of the same function finishes.
const updateStatistics = promiseUtils.debounce(function (geometry) {
  return layerView.queryFeatures({
    geometry,
    distance: 1,
    units: "kilometers",
    outStatistics: [{
      onStatisticField: "*",
      outStatisticFieldName: "feature_count",
      statisticType: "count"
    }]
  }).then(function(featureSet) {
    console.log(`Feature Count: ${featureSet.features[0].attributes["feature_count"]}`);
  });
});

view.on("drag", (event) => updateStatistics(view.toMap(event)));
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:
const controller = new AbortController();

// 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, {
      signal: controller.signal
    });
  }));
}

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...