Method Overview

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:

Type	Description
Promise	A 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:

Type	Description
Promise | Object	If 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.

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

Returns:

Type	Description
Promise	A 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:

Type	Description
Promise	A 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:

Type	Description
Promise	A 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

EachAlwaysResultObject

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()

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

Properties:

resolve ResolveCallback A function that will fulfill the promise.

reject RejectCallback 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:

Type	Description
Promise	A promise that resolves to a boolean value, indicating whether the entry should be kept in the filtered array.

RejectCallback

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

Property:

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

ResolveCallback

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

Property:

value *|Promise<*> optional The value with which the promise resolved. Defined only if the promise is fulfilled.